Guides
Guides
Product ChangesContact Us

Chat API

Chat with your bots via API

Suggest Edits

📘

Don't have an Instabot account yet?

Start your free trial today!

Contents

  1. Start chat
  2. Respond to chat
  3. Live chat
  4. Supported node types
  5. Get user

1. Start chat

In order to start chat post the JSON below to /secure/send

{
  "apiKey": "API_KEY",
  "start": true,
  "botId": 474960032,
  "email": "[email protected]",
  "callbackUrl": "WEBHOOK",
  "metadata": { "somekey": "somevalue" }
}
  • apiKey (required) - your API key
  • start (required) - indicates that new chat should be created
  • botId (required) - id of the bot
  • email (required) - email of the user
  • callbackUrl - url that receives live agent messages
  • metadata - key-value data


Response will be the following:

{
    "messages": [
        {
            "text": "Hello!"
        },
        {
            "text": "Please choose an option",
            "quick_replies": [
                {
                    "content_type": "text",
                    "title": "Option 1",
                    "payload": 478137613
                },
                {
                    "content_type": "text",
                    "title": "Option 2",
                    "payload": 478137614
                },
            ]
        }
    ],
    "streamId": "478158890"
}
  • messages - array of the messages that should be shown to the user
    • text - text of the message
    • quick_replies - array of the multiple choice options
  • streamId - id of created chat, should be passed with the subsequent calls during this chat

2. Respond to chat

In order to respond to chat post the JSON below to /secure/send

{
  "streamId": "478158890",
  "message": {
      "text": "Option 1",
      "payload": 478137613
  }
}
  • streamId (required) - id of created chat
  • message
    • text (required) - text of the message
    • payload (required for multiple choice node) - payload of the item selected from quick_replies array

3. Live chat

Whenever a live agent action is invoked there will be a POST request to callbackUrl that was provided in chat start with the following JSON

{
  "streamId": "478158890",
  "text": "Agent has ended this live session"
}

In order to respond to live agent use API defined in 2. Respond to chat

4. Supported node types

Be aware that not all node types are supported via API, here is the list of supported types:

  • Multiple Choice (Buttons and Limit user to selecting only 1 button only)
  • Free Text Reply
  • No Reply
  • User's Name
  • Email Address
  • Phone number
  • Link to an Existing Node
  • Conditional Logic
  • Script Node (Run on server only)
  • Dialogflow

Custom plugins are also supported

5. Get user

In order to get user post the JSON below to /secure/user

{
  "apiKey": "API_KEY",
  "email": "[email protected]"
}
  • apiKey (required) - your API key
  • email (required) - email of the user


Response will be the following:

{
    "objectId": 478187758,
    "developmentCompany": {
        "objectId": 520801656
    },
    "name": "[email protected]",
    "friendlyName": "[email protected]",
    "isDefaultFriendlyName": true,
    "createDate": "2022-06-08T08:44:08.002Z",
    "firstLoginTime": "2022-06-08T08:44:08.002Z",
    "lastLoginTime": "2022-06-08T08:44:08.002Z",
    "username": "[email protected]",
    "status": 1,
    "applications": [
        {
            "trialPeriodEndDate": null,
            "isTrial": null,
            "createDate": "0001-01-01T00:00:00Z",
            "updateDate": "0001-01-01T00:00:00Z",
            "components": null,
            "isSample": false,
            "isMobiComponentsEnabled": false,
            "hideBrandedFooterInChat": false,
            "subscriptionStartDate": null,
            "subscriptionEndDate": null,
            "isTrialOrSubscriptionEnded": false,
            "isActive": false,
            "webSite": null,
            "timeZone": null,
            "participationLevel": 0,
            "status": 0,
            "botDomains": null,
            "botLimit": null,
            "objectId": 474952131
        }
    ],
    "systemProperties": {
        "clientPlatform": 3
    },
    "userSegments": null,
    "userType": 2,
    "lastActivityDate": "2022-06-08T08:44:08.034Z",
    "requestInfo": {},
    "visitInfo": [],
    "rowVersion": 47288359,
    "ipAddress": "",
    "isTestUser": false,
    "updateDate": "2022-06-08T08:44:08.034Z",
    "customProperties": {
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null
    }
}

Updated almost 2 years ago