Newborn Programming Monsters

    controltower-api

    0.3.1 • Public • Published

    Control Tower API

    A REST API to be used with https://github.com/calamar-io/controltower

    This API is extremely experimental and will have constant breaking changes. Consider yourself warned.

    This document is a draft!

    Patches are welcome

    If you are a contributor, see the CONTRIBUTING.md file for instructions on how to setup the developer environment to write your patches.

    Endpoints

    endpoint methods requires authentication
    /v1/customers POST yes
    /v1/customers/{ customerId } GET, PUT yes
    /v1/bots POST yes
    /v1/bots/{ botId } GET, PUT yes
    /v1/users POST, GET, PUT yes
    /v1/users/{ userId } GET, PUT yes

    Authenticated requests

    For using endpoints that requires authentication, you must pass an Authentication header with the value Bearer your_access_token. The access token for the v1 of this api is a Facebook accessToken that can be obtained with a Facebook Login Popup using the app ID of a facebook app that your API server is configured to expect (step 1.1 of the Contributing Guide).

    Example:

    curl --request GET \
      --url https://api.example.com/latest/v1/customers/048c37f5-17fb-4f3f-82de-8014230d3922 \
      --header 'authorization: Bearer EAA...ZD' \
      --header 'content-type: application/json'

    Customers

    The customers of the system. Example: a paying customer that has access to an administrative interface where she can setup programs (bots) that interact/chat with her customers (users).

    Create a customer

    Will attempt to create a new customer connected with the Facebook user ID that generated the login access token.

    Returns the created Controltower user, or the existing one if there is one already for that Facebook user ID.

    Request

    POST /v1/customers

    Successful Response
    • 201 (application/json)
    {
        "id": "048c37f5-17fb-4f3f-82de-8014230d3922",
        "email": "fabricio@fabricio.org",
        "name": "Fabricio Campos Zuardi",
        "facebookId": "10154544223979636",
        "bots": []
    }

    Get customer info

    Request

    GET /v1/customers/{ customerId }

    Successful Response
    • 200 (application/json)
    {
        "id": "048c37f5-17fb-4f3f-82de-8014230d3922",
        "email": "fabricio@fabricio.org",
        "name": "Fabricio Campos Zuardi",
        "facebookId": "10154544223979636",
        "bots": []
    }

    Update customer info

    Request

    PUT /v1/customers/{ customerId }

    • body: a json containing the attributes and values to update
    curl example
    curl --request PUT \
      --url https://api.example.com/v1/customers/87df2a3e-7a68-43aa-bba2-f6fe6d08f089 \
      --header 'authorization: Bearer EAA...ZD' \
      --header 'content-type: application/json' \
      --data '{
        "name": "James Morgan McGill",
        "email": "james@example.com"
    }'
    Successful Response
    • 200 (application/json)
    {
        "id": "048c37f5-17fb-4f3f-82de-8014230d3922",
        "email": "james@example.com",
        "name": "James Morgan McGill",
        "facebookId": "10154544223979636",
        "bots": []
    }

    Bots

    Programs configured by system customers, that can listen/reply to users on chat platforms.

    Create a bot

    Request

    POST /v1/bots

    Successful Response
    • 200 (application/json)
    {
        "customerId": "87df2a3e-7a68-43aa-bba2-f6fe6d08f089",
        "id": "4853d957-1cde-4b37-b5d1-cdf14512114b",
        "users": []
    }

    Get bot config

    Request

    GET /v1/bots/{ botId }

    Query string parameters
    • customerId (optional)
    curl example
    curl --request GET \
      --url 'https://api.example.com/v1/bots/4cd94422-7598-4405-946a-1861ce9a4168?customerId=87df2a3e-7a68-43aa-bba2-f6fe6d08f089' \
      --header 'authorization: Bearer EAA...DZD' \
      --header 'content-type: application/json'
    Successful Response
    • 200 (application/json)
    {
        "id": "4cd94422-7598-4405-946a-1861ce9a4168",
        "customerId": "87df2a3e-7a68-43aa-bba2-f6fe6d08f089"
    }

    Update bot config

    Request

    PUT /v1/bots/{ botId }

    • body: a json containing the attributes and values to update
    curl example
    curl --request PUT \
      --url https://api.example.com/v1/bots/bc74d285-2fdf-4a77-990b-f412273bad5f \
      --header 'authorization: Bearer EAA...ZD' \
      --header 'content-type: application/json' \
      --data '{
        "foo": "bar",
        "bar": "foo"
    }'
    Successful Response
    • 200 (application/json)
    {
        "id": "bc74d285-2fdf-4a77-990b-f412273bad5f",
        "foo": "bar",
        "customerId": "87df2a3e-7a68-43aa-bba2-f6fe6d08f089",
        "bar": "foo"
    }
    Special cases
    Generate new bot config invite code

    If in the body of the request you send an "inviteCode" of value "new" then the existing inviteCode will be invalidated and a new one will be generated.

    Add a new customer to the list of bot admins

    If in the body of the request you send an "admins" key with value "me", and an "inviteCode" key with a valid inviteCode value, and a customerId with the id of the bot owner the customer making the request will be added to the admins access list of that bot.

    Example body:

    {
        "admins": "me",
        "inviteCode": "ry7ECzB0",
        "customerId": "735aa084-c5bb-4808-a8a2-ffe6d83f0c0d"
    }
    Remove a customer from the list of bot admins

    TBD

    Users

    An user is a recipient that a bot can chat to. Examples: a messenger user, a chat group, an IRC channel…

    Create a user

    Request

    POST /v1/users

    • body: a json containing information about the chat session (facebook Id of the recipient) and the bot listening to that session (botId). Optionally you can also include the id of the customer that owns that bot (customerId) to speed things up.
      • example body:
      {
          "botId": "4853d957-1cde-4b37-b5d1-cdf14512114b",
          "customerId": "87df2a3e-7a68-43aa-bba2-f6fe6d08f089",
          "facebookId": "10154544223979636"
      }
    
    ##### Successful Response
    - 200 (application/json)
    
    ```json
    {
        "botId": "4853d957-1cde-4b37-b5d1-cdf14512114b",
        "id": "db00fe66-0475-4471-9bb7-b3f099bd6e97",
        "facebookId": "10154544223979636"
    }
    

    Get user info

    GET /v1/users/{ userId }

    Query string parameters
    • botId (required)
    • customerId (optional)
    Successful Response
    • 200 (application/json)
    {
        "botId": "4853d957-1cde-4b37-b5d1-cdf14512114b",
        "id": "050e8b79-f52b-4746-8672-c45b83582049",
        "facebookId": "10154544223979636"
    }

    Query users with muted bot

    GET /v1/users

    Query string parameters
    • botId
    curl example
    curl --request GET \
      --url 'https://api.example.com/v1/users?botId=00950d32-2059-42c7-8f91-b30515fc7f15' \
      --header 'authorization: Bearer EAA...DZD' \
      --header 'content-type: application/json'
     
    Successful Response
    • 200 (application/json)
    [
        {
            "botId": "00950d32-2059-42c7-8f91-b30515fc7f15",
            "id": "52f42726-9f8d-4728-bbf2-7229bc753769",
            "botStatus": "muted",
            "facebookId": "10154544223979636"
        }
    ]
    Unmute bot for multiple users

    PUT /v1/users

    curl example
    curl --request PUT \
      --url https://api.example.com/v1/users \
      --header 'authorization: Bearer EAA...DZD' \
      --header 'content-type: application/json' \
      --data '{
        "ids": [
            "52f42726-9f8d-4728-bbf2-7229bc753769",
            "52f42726-9f8d-4728-bbf2-7229bc753769"
        ],
        "botId": "00950d32-2059-42c7-8f91-b30515fc7f15",
        "update": {
            "botStatus": "muted"
        }
    }'

    Update user info

    PUT /v1/users/{ userId }

    • body: a json containing the list of ids of users to change, the botId and an update attribute containing the attributes to update on all users.
    curl example
    curl --request PUT \
      --url https://api.example.com/latest/v1/users \
      --header 'authorization: Bearer EAA...ZD' \
      --header 'content-type: application/json' \
      --data '{
        "ids": [
            "52f42726-9f8d-4728-bbf2-7229bc753769",
            "a17f26f6-85b4-4502-b1aa-6fdae8b6af81"
        ],
        "botId": "00950d32-2059-42c7-8f91-b30515fc7f15",
        "update": {
            "botStatus": "muted"
        }
    }'
    Successful Response
    • 200 (application/json)
    {
        "botId": "00950d32-2059-42c7-8f91-b30515fc7f15",
        "id": "52f42726-9f8d-4728-bbf2-7229bc753769",
        "facebookId": "10154544223979636",
        "botStatus": "active"
    }

    Examples of error responses

    • 500 (text/plain)
    {
        "error": {
            "message": "No authorization header"
        }
    }
    • 500 (text/plain)
    {
        "error": {
            "message": "Invalid customerId"
        }
    }
    • 500 (text/plain)
    {
        "error": {
            "message": "Malformed access token",
            "type": "OAuthException",
            "code": 190,
            "fbtrace_id": "Aj+ON1w7Fl8"
        }
    }
    • 500 (text/plain)
    {
        "error": {
            "message": "The access token could not be decrypted",
            "type": "OAuthException",
            "code": 190,
            "fbtrace_id": "HJYUlys/FGb"
        }
    }
    • 500 (text/plain)
    {
        "error": {
            "message": "Error validating access token: The session is invalid because the user logged out.",
            "type": "OAuthException",
            "code": 190,
            "error_subcode": 467,
            "fbtrace_id": "DIOWQtQq2KC"
        }
    }
    • 500 (text/plain)
    {
        "error": {
            "message": "Error validating access token: Session has expired on Wednesday, 07-Sep-16 22:00:00 PDT. The current time is Wednesday, 07-Sep-16 22:05:47 PDT.",
            "type": "OAuthException",
            "code": 190,
            "error_subcode": 463,
            "fbtrace_id": "Cj21SvLn4aZ"
        }
    }

    Install

    npm i controltower-api

    DownloadsWeekly Downloads

    1

    Version

    0.3.1

    License

    AGPL-3.0

    Last publish

    Collaborators

    • fczuardi