Botsplash API v1.0.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Welcome to the Botsplash Open API!
Using this API, Botsplash's clients and partners can integrate thier 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 integrations@botsplash.com.
Base URLs:
Authentication
HTTP Authentication, scheme: basic HTTP Basic Authentication. Require username and password.
API Key (apiKey)
- Parameter Name: api_key, in: query. API Key Autentication. Require encrypted API key. Could be passed in the API request query string or body.
Either Basic Authentication or API key access is required for all API calls.
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:
- Enagage CRM Visitor with a pre-defined flow
- Reminder or notify a CRM visitor
- Enagage New Lead from Lead Provider with a defined flow
New Visitor Post
Code samples
# You can also use wget
curl -X POST https://api.botsplash.com/open/v1/{appId}/listener/botsplash/{id} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST https://api.botsplash.com/open/v1/{appId}/listener/botsplash/{id} HTTP/1.1
Host: api.botsplash.com
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = '{
"visitor": {
"clientVisitorId": "string",
"agentClientUserId": "string",
"teamCode": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"state": "string",
"tzName": "string",
"deliveryStatus": 0,
"extendedAttributes": {}
},
"args": {
"message": "string"
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.botsplash.com/open/v1/{appId}/listener/botsplash/{id}',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.botsplash.com/open/v1/{appId}/listener/botsplash/{id}', params={
}, headers = headers)
print r.json()
POST /{appId}/listener/botsplash/{id}
Submit visitor information to endpoint using botsplash schema. The submitted user information will be engaged on conversation channels as configured in the routing workflow.
Body parameter
{
"visitor": {
"clientVisitorId": "string",
"agentClientUserId": "string",
"teamCode": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"state": "string",
"tzName": "string",
"deliveryStatus": 0,
"extendedAttributes": {}
},
"args": {
"message": "string"
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | ListenerRequest | true | Visitor information to engage on conversation channels |
| » visitor | body | object | true | none |
| »» clientVisitorId | body | string | false | Optional Client CRM id for the customer. This identifier will be used during identification and dedupe process. |
| »» agentClientUserId | body | string | false | Optional client primary Employee ID assigned to the customer. If there are multiple agents assigned to the customer, include all of them in an array with first one being the primary. |
| »» teamCode | body | string | false | Optional team assigned to the customer. |
| »» firstName | body | string | false | Optional but recommended customer first name field. |
| »» lastName | body | string | false | Optional but recommended customer last name field. |
| body | string | false | Optional but recommended customer email field. | |
| »» phoneNumber | body | string | true | Customer phone number field. |
| »» state | body | string | false | US State Code. ie. NC, CA, VA, etc |
| »» tzName | body | string | false | Customer timezone to be used for TCPA compliance. Standard timezones such as America/New_York, America/Chicago, etc are required to be passed for evaluation. |
| »» deliveryStatus | body | number | false | Inital deliver status. Use 202 value for the new campaigns to override previous unsubcribes from the same customer. For more detail, see Delivery Status schema reference. |
| »» extendedAttributes | body | object | false | Additional attributes to pass with visitor profile. These attributes can be used in the botsplash dashboard for building workflow routing rules or custom reports. |
| » args | body | object | false | Request arguments |
| »» message | body | string | false | Default message to be sent to vistor |
| appId | path | string | true | 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 botton of the page. |
| id | path | string | true | Unique Listener Id as defined in Admin Listener Settings. The same listener Id is used to setup the routing workflow. |
Example responses
200 Response
{
"success": true,
"requestId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Success | ListenerRequestResult |
| default | Default | Error | ErrorResponse |
New LendingTree Lead Post
Code samples
# You can also use wget
curl -X POST https://api.botsplash.com/open/v1/{appId}/listener/lendingtree/{id} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST https://api.botsplash.com/open/v1/{appId}/listener/lendingtree/{id} HTTP/1.1
Host: api.botsplash.com
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = '{}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.botsplash.com/open/v1/{appId}/listener/lendingtree/{id}',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.botsplash.com/open/v1/{appId}/listener/lendingtree/{id}', params={
}, headers = headers)
print r.json()
POST /{appId}/listener/lendingtree/{id}
Endpoint to accept LendingTree lead information. This enpoint accepts and returns with LendingTree XML format.
Use of API key authentication is recommended for LendingTree endpoint to simplify setup process.
Body parameter
{}
<?xml version="1.0" encoding="UTF-8" ?>
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | LendingTree Lead Submission XML. See LendingTree documentation for more detials. |
| appId | path | string | true | 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 botton of the page. |
| id | path | string | true | none |
Example responses
default Response
{}
<?xml version="1.0" encoding="UTF-8" ?>
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| default | Default | LendingTree Lead Error Resonse XML. See LendingTree documentation for more detials. | Inline |
Response Schema
New SalesForce Lead Post
Code samples
# You can also use wget
curl -X POST https://api.botsplash.com/open/v1/{appId}/listener/salesforce/{id} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST https://api.botsplash.com/open/v1/{appId}/listener/salesforce/{id} HTTP/1.1
Host: api.botsplash.com
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = '{
"visitors": null,
"args": {
"message": "string"
}
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.botsplash.com/open/v1/{appId}/listener/salesforce/{id}',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.botsplash.com/open/v1/{appId}/listener/salesforce/{id}', params={
}, headers = headers)
print r.json()
POST /{appId}/listener/salesforce/{id}
Submit bulk visitor information to endpoint using botsplash schema. The submitted user information will be engaged on conversation channels as configured in the routing workflow.
Body parameter
{
"visitors": null,
"args": {
"message": "string"
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | ListenerRequestBulkVisitors | true | Visitor information to engage on conversation channels |
| » visitors | body | any | true | none |
| » args | body | object | false | Request arguments |
| »» message | body | string | false | Default message to be sent to vistor |
| appId | path | string | true | 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 botton of the page. |
| id | path | string | true | Unique Listener Id as defined in Admin Listener Settings. The same listener Id is used to setup the routing workflow. |
Example responses
200 Response
[
{
"success": true,
"requestId": "string"
}
]
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Success | ListenerRequestBulkVisitorsResult |
| default | Default | Error | ErrorResponse |
Messages
Visitor Chat Transcript and Messages. Use this endpoint to send or access chat trascripts or messages across all channels.
Send Message
Code samples
# You can also use wget
curl -X POST https://api.botsplash.com/open/v1/{appId}/message \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
POST https://api.botsplash.com/open/v1/{appId}/message HTTP/1.1
Host: api.botsplash.com
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = '{
"text": "string",
"visitor": null
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://api.botsplash.com/open/v1/{appId}/message',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json'
}
r = requests.post('https://api.botsplash.com/open/v1/{appId}/message', params={
}, headers = headers)
print r.json()
POST /{appId}/message
Send direct message to your visitors using thier CRM ID and phone number. This enables external CRM applications to follow up a visitor without leaving CRM dashboard.
Body parameter
{
"text": "string",
"visitor": null
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | object | true | Visitor message request body |
| » text | body | string | true | Message text to send to the visitor |
| » visitor | body | any | false | none |
| appId | path | string | true | 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 botton of the page. |
Example responses
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Success | None |
Response Schema
Schemas
ListenerRequest
{
"visitor": {
"clientVisitorId": "string",
"agentClientUserId": "string",
"teamCode": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"state": "string",
"tzName": "string",
"deliveryStatus": 0,
"extendedAttributes": {}
},
"args": {
"message": "string"
}
}
Listener request data to initiate engagement with visitors
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| visitor | VisitorNewSubmit | true | none | none |
| args | object | false | none | Request arguments |
| » message | string | false | none | Default message to be sent to vistor |
ListenerRequestBulkVisitors
{
"visitors": null,
"args": {
"message": "string"
}
}
Listener request data to initiate engagement with visitors
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| visitors | VisitorsArrayNewSubmit | true | none | none |
| args | object | false | none | Request arguments |
| » message | string | false | none | Default message to be sent to vistor |
ListenerRequestResult
{
"success": true,
"requestId": "string"
}
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | none |
| requestId | string(uuid) | true | none | request message id |
ListenerRequestBulkVisitorsResult
[
{
"success": true,
"requestId": "string"
}
]
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | [ListenerRequestResult] | false | none | none |
VisitorNewSubmit
{
"clientVisitorId": "string",
"agentClientUserId": "string",
"teamCode": "string",
"firstName": "string",
"lastName": "string",
"email": "string",
"phoneNumber": "string",
"state": "string",
"tzName": "string",
"deliveryStatus": 0,
"extendedAttributes": {}
}
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| clientVisitorId | string | false | none | Optional Client CRM id for the customer. This identifier will be used during identification and dedupe process. |
| agentClientUserId | string | false | none | Optional client primary Employee ID assigned to the customer. If there are multiple agents assigned to the customer, include all of them in an array with first one being the primary. |
| teamCode | string | false | none | Optional team assigned to the customer. |
| firstName | string | false | none | Optional but recommended customer first name field. |
| lastName | string | false | none | Optional but recommended customer last name field. |
| string | false | none | Optional but recommended customer email field. | |
| phoneNumber | string | true | none | Customer phone number field. |
| state | string | false | none | US State Code. ie. NC, CA, VA, etc |
| tzName | string | false | none | Customer timezone to be used for TCPA compliance. Standard timezones such as America/New_York, America/Chicago, etc are required to be passed for evaluation. |
| deliveryStatus | number | false | none | Inital deliver status. Use 202 value for the new campaigns to override previous unsubcribes from the same customer. For more detail, see Delivery Status schema reference. |
| extendedAttributes | object | false | none | Additional attributes to pass with visitor profile. These attributes can be used in the botsplash dashboard for building workflow routing rules or custom reports. |
ErrorResponse
{
"message": "string"
}
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | none |