Guides
NewsPricingSystem StatusBook DemoFree Trial

Messaging APIs

Authentication

All of Proto's RESTful APIs calls must be authenticated. Instead of passing the full credentials on every REST API call, Proto uses a personal access token. The Proto AICX platform users can find their personal access token in the profile page.

👍

Best Practice

Use an Admin account that is not linked to any user's personal email address to avoid lock-out when the user is no longer employed by the company.

To create your Personal Access Token (PAT)

  1. On the top-right corner, click on your avatar
  2. Select "Profile"
  3. On the horizontal menu, select "API"
  4. If you never created a PAT before, click "Issue new token"
  5. Save the token safe somewhere. Anyone with this token could gain access to your account.

To use the RESTful APIs, authenticate it with your PAT by passing it in X-PROTO-TOKEN header. For example,

curl --header "X-PROTO-TOKEN: <PERSONAL ACCESS TOKEN>" "https://gw.proto.cx/webhook/"

Human APIs

POST https://gw.proto.cx/webhook/{channel_id}/human

To create a Human (customer)

{
  "name": "...",
  "email": "...",
  "phoneNumber": "..." ,
  "profilePicUrl": "...",
  "tags": [
    { "id": "9e763004dffb47b4a44e7915dc2026f6", "name": "VIP", "value": 1},
    { "id": "5703bdefe5e74660993bf0137dacf549", "name": "locale", "value": ["en", "fr"]},
  ],
  "accessToken": "...", // if provided, it will be included in the webhooks.
  "externalId": "..."  // If provided, it will be included in report.
}

{
  "human": {
     "id": "human_4361a99d71fa3"
   }
}

GET https://gw.proto.cx/webhook/{channel_id}/human/{human_id}

Get Human information

{
  "id": "human_4361a99d71fa3",       
  "name": "...",
  "email": "...",
  "phoneNumber": "..." ,
  "profilePicUrl": "...",
  "tags": [
    { "id": "9e763004dffb47b4a44e7915dc2026f6", "value": "1"},
    { "id": "5703bdefe5e74660993bf0137dacf549", "value": "en, fr"},
  ],
  "accessToken": "...",
  "externalId": "..." 
}

Chat APIs

POST https://gw.proto.cx/webhook/{channel_id}/chat

Create a chat

You can also create or update a Human on the fly. The API returns a Chat ID. Third-party messaging platforms may also provide a chat token that Proto can later use to send replies.

{
  "human": { // Optional. Proto will automatically create a new one if omitted.
    "id": "human_4361a99d71fa3",
    "name": "...",
    "email": "...",
    "tags": [
        { "id": "9e763004dffb47b4a44e7915dc2026f6", "value": "3"},
        { "id": "5703bdefe5e74660993bf0137dacf549", "value": "en,fr"}
     ],
    "externalId": "..."  // If provided, it will be included in report.

  },
  "data": { //data to initialize the bot.
      "ip": "123.45.67.89",
      "source": "website"
  },
  "lang": "en", //Optional. You can specify the language to start the chat. Proto will use the master language if omitted
  "chatToken": "Rb0PU9LqrGnTkWbO4X2Ry33oAQKWJFDnJTrSTA4rcyjfwQ6" //Optional. If provided, it will be included in the webhooks.
}

{
    "chat": {
      "id": "e0fdaa11427340d08527ce0a39939b7d",
      "active": true,
      "createdAt": "2021-11-30T00:12:33Z",
      "human": {
        "id": "human_4361a99d71fa3",
        "name": "Customer's Name"
      }
    }
}

Here is the list of languages supported

  • en Englsh
  • zh_CN Simplified Chinese
  • zh_TW Tranditional Chinese
  • id Indonesia
  • ja Japanese
  • pt Portuguese
  • th Thai
  • tl Tagalog
  • vi Vietnamese
  • es Spanish
  • fr French
  • de Germany
  • ms Malay
  • yo Yoruba
  • ha Hausa
  • ig Igbo
  • hi Hindi
  • mr Marathi
  • bn Bengali
  • sw Swahili
  • rw Kinyarwanda
  • tw Twi
  • ceb Cebuano
  • bem Bemba (Zambia)
  • ny Nyanja
  • ar Arabic
  • kqn Kaonde
  • loz Lozi
  • lue Luvale
  • lun Lunda
  • ton Tonga

GET https://gw.proto.cx/webhook/{channel_id}/chats

List chats

Query string parameters

  • humanId String. Human ID to list the chats.
  • chatId String. Chat id to list.
  • max Integer. Maximum number of chats to return. Default to 5.

You have to provide at least one humanId or chatId.

[ 
  {
      "id": "e0fdaa11427340d08527ce0a39939b7d",
      "active": true,
      "createdAt": "2021-11-30T00:12:33Z",
      "human": {
        "id": "human_4361a99d71fa3",
        "name": "Customer's Name"
      },
      "lastMsg":{
          "author": {
            "type": "human",
            "id": "human_4361a99d71fa3"
          },
          "message": {
              "type": "text",
              "data": {
                  "text": "I can't see my deposit in my account"
              }
          }
     }
  }
]

POST https://gw.proto.cx/webhook/{channel_id}/chat/{chatId}/message

Send a message (as customer) to a Chat.

Use this API to notify Proto about customer events, such as texting a message, uploading an image, clicking a button, or leaving feedback. You may provide a replyToken that Proto could later use to send replies. (This is useful in some scenarios, for example, to force Proto to reply within a certain time frame after receiving a message. 

{
    "author": {
      "type": "human",
      "id": "human_4361a99d71fa3"
    },
    "message": {
        "type": "text",
        "data": {
            "text": "I can't see my deposit in my account"
        }
    },
    "replyToken": "qsua3e6akM04D15cSyIv6gZ7PPXGV1y8"  #Optional. If provided, it will be included in the webhooks.
}

Proto supports three kinds of customer message

  1. Text message: Customer submits a piece of text, selects a quick reply, or clicks on a Text Button.
  2. Postback Button message: Customer click on a Postback Button in Carousel or Cards.
  3. Manual Trigger message: To force the bot to jump the flow of a ManualTrigger Event.
  4. Media message: Customer uploads an image, audio, video, or other kinds of files.

The following are the formats of message fields.

Text message

{
  "type": "text",
  "data": {
      "text": "I can't see my deposit in my account"
  }
}

Postback Button message

{
  "type": "button",
  "data": {
      "payload": "the-postback-string"
  }
}

Manual Trigger message

{
  "type": "manual_trigger",
  "data": {
      "trigger_name": "The `API Code` defined in the ManualTigger Action",
      "payload": {}
  }
}

Media message

{
  "type":  "media",
  "data": {
  	"attachment": {
      "filename": "image.png",
      "url": "https://www.example.com/file/image.png"
    }
  }
}

GET https://gw.proto.cx/webhook/{channel_id}/chat/{chatId}/message

List messages of a chat

[
  {
    "author": {
      "type": "human",
      "id": "human_4361a99d71fa3"
    },
    "message": {
      "type": "text",
      "data": {
        "text": "I can't see my deposit in my account"
      }
    }
  },
  {
    "author": {
      "type": "bot",
      "id": "bot_53aqweas2saf"
    },
    "message": {
      "type": "text",
      "data": {
        "text": "I can help with that! Kindly let me know your email please?"
      }
    }
  }
]

📘

Note

Please see adding bot blocks to learn about chatbot message types that Proto supports.

Outbound Webhook

Proto chatbots will call your webhook to send messages to customers. Proto will include chatToken and/or replyToken if they are previously provided. It's recommended that your server returns 2xx status code as soon as possible.

All webhooks are sent in POST method.

Signature

Proto add a signature to each request in X-PROTO-SIGNATURE header. The signature is generated with HMAC-SHA1 algorithm, and it uses Channel Secrets as the key and request body as message.

Sample webhook

{
    "events": [
        {
            "chat": {
                "id": "e0fdaa11427340d08527ce0a39939b7d",

                "human": {
                    "id": "human_4361a99d71fa3",
                    "name": "Customer's Name"
                }
            },
            "chatToken": "Rb0PU9LqrGnTkWbO4X2Ry33oAQKWJFDnJTrSTA4rcyjfwQ6",
            "replyToken": "qsua3e6akM04D15cSyIv6gZ7PPXGV1y8",
            "messages": [
                {
                    "author": {
                        "type": "bot",
                        "id": "bot_XXXXXXXXXXXXXX",
                        "name": "Bot #1"
                    },
                    "type": "text",
                    "data": {
                        "text": "Let me find an available agent for you."
                    }
                },
                {
                    "author": {
                        "type": "bot",
                        "id": "bot_XXXXXXXXXXXXXX",
                        "name": "Bot #1"
                    },
                    "type": "image",
                    "data": {
                        "url": "https://api.proto.cx/gateway/attachment/smily-face.png"
                    }
                }
            ]
        },
        {
            "chat": {
                "id": "b7e3c0366cea4970804a76f028fb36f8",
                "human": {
                    "id": "human_0a129df726461823",
                    "name": "Customer2's Name"
                }
            },
            "chatToken": "Rb0PU9LqrGnTkWbO4X2Ry33oAQKWJFDnJTrSTA4rcyjfwQ6",
            "replyToken": "qsua3e6akM04D15cSyIv6gZ7PPXGV1y8",
            "messages": [
                {
                    "author": {
                        "type": "agent",
                        "name": "Alex",
                        "id": "user_XXXXXXXXXXX (user ID on Proto)"
                    },
                    "type": "text",
                    "data": {
                        "text": "How may I help you?"
                    }
                }
            ]
        }
    ]
}

Human profile Webhook

Proto chatbots will call this webhook to fetch customer profile data, such as full name, email, gender, and phone number. 

{
    "human": "anUniversallyUniqueUserId",
    "chatToken": "Rb0PU9LqrGnTkWbO4X2Ry33oAQKWJFDnJTrSTA4rcyjfwQ6",
}

This webhook is optional, which means the bot will still be operating even if this webhook doesn't response. However, if you'd like to handle this event, Proto expects you to respond in the following format. You can also use the Human API to update a Human actively.

{
    "result": {
      "name": "John",
      "email": "[email protected]",
      "tags": [
        { "id": "9e763004dffb47b4a44e7915dc2026f6", "name": "VIP", "value": 3},
        { "id": "5703bdefe5e74660993bf0137dacf549", "name": "locale", "value": ["en", "fr"]},
      ]
    }
}

Updated about 1 year ago