logo
API docs by Redocly

Botsplash API (1.0.0)

Download OpenAPI specification:

Welcome to the Botsplash Open API!

Using this API, Botsplash's clients and partners can integrate their applications to communicate with Botsplash platform to seamlessly engage with customers.

We have language bindings in Shell, NodeJs and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This API is restricted to selected Botsplash clients and partners. Please contact Botsplash support for setting up API access, IP Whitelisting or for help with troubleshooting the API access at support@botsplash.com.

Listeners

Listeners are the entry points into Botsplash platform. Use this endpoint to submit CRM visitor information or new lead data to initiate engagement from conversation channels.

Use cases:

  • Engage CRM Visitor with a pre-defined flow
  • Reminder or notify a CRM visitor
  • Engage New Lead from Lead Provider with a defined flow

New Listener Post

Submit visitor information to endpoint using Botsplash schema. The submitted user information will be engaged on conversation channels as configured in the routing workflow.

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

id
required
string

Unique Listener Id as defined in Admin Listener Settings. The same listener Id is used to setup the routing workflow.

Request Body schema: application/json
required

Visitor information to engage on conversation channels.

required
object (VisitorNewSubmit)
object

Request arguments

Responses

Request samples

Content type
application/json
{
  • "visitor": {
    },
  • "args": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Upload a file

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

Request Body schema: multipart/form-data
file
string <binary>

The file to upload

Responses

Response samples

Content type
application/json
{
  • "key": "Uploaded file key"
}

Sequences

Creates or updates a visitor and triggers the sequence.

Create/Update Visitor and Trigger Sequence

Creates or updates a visitor with the provided payload and triggers the specified sequence.

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

id
required
string
Request Body schema: application/json
required

Request body containing visitor information to create/update and engage with the sequence.

required
object (VisitorInfo)

Responses

Request samples

Content type
application/json
{
  • "visitor": {
    }
}

Response samples

Content type
application/json
{
  • "visitorId": "string",
  • "visitorSequenceId": "string",
  • "visitorUrl": "string",
  • "success": true
}

Visitors

Visitors listing and updates to agent assignment.

Update Visitor

Update Visitor information including Agent Assignment using External ID

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

idType
required
string

Type of the external Id. Currently supports 'clientVisitorId' and 'clientAppId'

idValue
required
string

Value of the 'idTye' specified.

Request Body schema: application/json
required

Visitor submit body

updateOnly
boolean

Will search for visitor ID. If visitor found, their info will be updated. If not found:

True - It will return 400 error code.
False - It will create new visitor.

agentUpdate
boolean

Allows agents already connected to be notified that message was sent to visitor.

retainAccess
boolean

When visitor is transfered to another agent, this will allow the original agent to retain access.

retainPhones
boolean

Option to add to existing phone number(s), otherwise will replace current phone number(s).

object (VisitorInfo)

Responses

Request samples

Content type
application/json
{
  • "updateOnly": true,
  • "agentUpdate": true,
  • "retainAccess": true,
  • "retainPhones": true,
  • "visitor": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientVisitorId": "12345",
  • "handle": "string",
  • "agentId": "string",
  • "agentClientUserId": "54321",
  • "teamId": "a4ede8ba-7c0a-4485-8763-cbd9b282fbec",
  • "teamCode": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phoneNumber": "string",
  • "pictureUrl": "string",
  • "city": "string",
  • "state": "NC",
  • "milestone": "SUPER",
  • "visitorStatus": "Contacted",
  • "tzName": "America/New_York",
  • "archived": true,
  • "deliveryStatus": null
}

Call Visitor Action

Call Visitor Action by External ID such as clientVisitorId or clientAppId

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

idType
required
string

Type of the external Id. Currently supports 'clientVisitorId' and 'clientAppId'

idValue
required
string

Value of the 'idTye' specified.

actionId
required
string

Action Id

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientVisitorId": "12345",
  • "handle": "string",
  • "agentId": "string",
  • "agentClientUserId": "54321",
  • "teamId": "a4ede8ba-7c0a-4485-8763-cbd9b282fbec",
  • "teamCode": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phoneNumber": "string",
  • "pictureUrl": "string",
  • "city": "string",
  • "state": "NC",
  • "milestone": "SUPER",
  • "visitorStatus": "Contacted",
  • "tzName": "America/New_York",
  • "archived": true,
  • "deliveryStatus": null
}

Meetings

Schedule and list meetings for a visitor.

List Visitor Meetings

Returns the list of meetings for the visitor matched by External ID

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

idType
required
string

Type of the external Id. Currently supports 'clientVisitorId' and 'clientAppId'

idValue
required
string

Value of the 'idTye' specified.

Responses

Response samples

Content type
application/json
{
  • "visitorId": "string",
  • "count": 0,
  • "meetings": [
    ]
}

Schedule Visitor Meeting

Schedule a meeting for an existing visitor matched by External ID with the specified agent. The visitor must already exist or a 400 error is returned.

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

idType
required
string

Type of the external Id. Currently supports 'clientVisitorId' and 'clientAppId'

idValue
required
string

Value of the 'idTye' specified.

Request Body schema: application/json
required

Meeting submit body

agentClientUserId
required
string

Client-specific agent or employee ID the meeting is scheduled with.

followupAt
required
string <date-time>

Meeting date/time in ISO format. Must be a future date/time.

duration
integer
Default: 30

Meeting duration in minutes. Defaults to 30.

notes
string

Optional notes included with the meeting.

description
string

Optional description for the meeting activity. Defaults to "Meeting scheduled via API".

additionalEmails
Array of strings

Additional invitee email addresses.

Responses

Request samples

Content type
application/json
{
  • "agentClientUserId": "string",
  • "followupAt": "2019-08-24T14:15:22Z",
  • "duration": 30,
  • "notes": "string",
  • "description": "string",
  • "additionalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "visitorId": "string",
  • "meetingId": "string",
  • "followupAt": "2019-08-24T14:15:22Z",
  • "updateError": "string",
  • "visitorUrl": "string"
}

Messaging

Send Direct Messages as the Agent

Send Message

Send direct message to your visitors using their CRM ID and phone number. This enables external CRM applications to follow up a visitor without leaving CRM dashboard.

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

Request Body schema: application/json
required

Visitor message request body.

text
required
string

Message text to send to the visitor.

object (VisitorInfo)

Responses

Request samples

Content type
application/json
{
  • "text": "Welcome!",
  • "visitor": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientVisitorId": "12345",
  • "handle": "string",
  • "agentId": "string",
  • "agentClientUserId": "54321",
  • "teamId": "a4ede8ba-7c0a-4485-8763-cbd9b282fbec",
  • "teamCode": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phoneNumber": "string",
  • "pictureUrl": "string",
  • "city": "string",
  • "state": "NC",
  • "milestone": "SUPER",
  • "visitorStatus": "Contacted",
  • "tzName": "America/New_York",
  • "archived": true,
  • "deliveryStatus": null
}

DeliveryStatus

Delivery status change notifications.

Delivery Status Update

Updates the visitor with phone numbers send in request params to respective status

Authorizations:
basicAuthapiKey
path Parameters
appId
required
string

Botsplash Account App Name or ID. App Name and ID can be found in "Settings" -> "App Info" -> "Company Info" -> "Identifier" textbox or "App ID" defined at the bottom of the page.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "count": 0
}