API Medium Integration

API Medium Overview

The API medium integration allows running chat bot user sessions with asynchronous API calls. This medium is well suited for use in custom built applications or interfaces. Note: This medium requires technical knowledge to implement successfully and is only supported for the Pro and Enterprise plans.

The medium works by allowing user messages to be sent to our API for processing. If the user message request was well formed, we'll return a successful response, indicating the user message has been received. When a chat bot reply is complete, the webhook you define will receive an event with the chat bot reply.



API Medium Setup

Creating an API Channel

To setup or manage an API channel, go to the Management Dashboard, then the SETTINGS page, and under Integrations select the API medium Integration.

To add a channel, click the "Add Channel" button:

You may now configure the new channel in the dialog that opens. Each field is used like so:

  • Channel ID: Identifies your channel in the interface, and is used in API calls to identify the channel. An ID is generated at creation time, but may be changed.
  • Channel Token: The token used to authenticate requests to the channel. A token is generated at creation time, but may be changed.
  • Webhook URL: Where bot & agent messages are sent. Your webhook must accept JSON & should return a 200 response. If you're still setting up a webhook url, webhook.site is a simple & free alternative to help you test.

The "Test Webhook" button sends a sample request to your configured webhook to confirm it is working as expected. The "Request Example" section contains helpful details to get you started with sending messages via this API channel.

 Note:Your webhook doesn't need to display as "Reachable" with the "Test Webhook" button before saving.


When all fields are satisfied, you can click "Create" to create your new API channel. It will show up in the 'API Medium Integration' table & may be reconfigured or deleted via the button in the table:

Note: Deleting an API channel will delete any chat bot deployments using it.

Deploying to API Channels

Once your API channel is created, you may deploy it from the CHATBOTS page or within the flow diagram editor like any other medium.

From the CHATBOTS page, you can select your "Ready to Deploy" bot, click the "</>" button in the right side panel, then click "ADD API DEPLOYMENT" to deploy it to your channel:


From the Bot Builder, you can "Save & Deploy" your bot, then from the drop down choose "Deploy to API Channel":

Then you can choose your channel in the next dialog, and click deploy when you're ready:



API Medium Usage

With your medium configured in the dashboard, you're now ready to send & receive messages via the API. The easiest way to start sending messages with your channel is via the "Request Example" section of the channel configuration:


Sending API Messages

You must POST to https://sub.domain.io/chatapi/webhooks/api-channel, where the domain is the same one you use to sign into the dashboard, with a request formatted like the provided example. The route may vary based on which instance your account is hosted on. 

Note: API Channel Messages you send us are subject to rate limiting according to your plan. See our API documentation for more information.


The following fields may be provided:
  • channelID (Required - String): The ID of the API channel this message is going to.
  • token (Required - String): The api token associated with the API channel.
  • message (Required - String): The message being sent to us.
    • If a user is starting a bot, the message is the hashtag (keyword) you defined for the bot deployment on this API channel.
  • userID(Optional - Number): The ID of the user to associate this message with. 
    • If not provided, we'll create a new user & reply with the generated ID.
  • attachments (Optional - Array[Object]): An array of attachments for this message. Each attachment can be provided in either of the following formats:
    • { "base64": "data:image/jpeg;base64,/12345/base64content" }
    • { "url": "https://www.example.com/image.jpg" }

Once a request is made, we'll respond as soon as your message is queued for processing. Successful responses look like:

{
    "channelID": "D9LjuWl0jappznT5"
    "message": "Hi there, I'm a user!",
    "userID": 9,
    "success": true,
}

If you didn't provide a userID in the request, we'll respond with the generated userID for your records. If we run into an error, we'll respond with it.


Receiving API Messages

Once you've sent a valid API message request it can take up to 60 seconds for your message to be processed, depending on the current volume of messages. When the message is sent to your webhook, the following fields may be present:

  • channelID (Required - String): The API channel the reply is coming from.
  • message (Required - String): The message being sent from us.
  • userID (Required - Number): The ID of the user to associate this message with. 
  • timestamp (Required - Number): The UTC time, in milliseconds, the message was sent.
  • quickReplies (Optional - Array[String]): The quick replies provided from the bot as options for the user.
  • attachments (Optional - Array[Object]): An array of attachments in the message. Each attachment provides an offset and url to help reconstruct the message with any specific attachment formatting.
  • adminID(Optional - Number): the ID of the admin who sent this message. Admin messages may be sent from within your account dashboard. 
    • This field is only included for messages coming directly from an dashboard user.
Was this article helpful?