NAV Navbar
Shell HTTP Node.JS Python
  • Botsplash API v1.0.0
  • Authentication
  • Listeners
  • Messages
  • Schemas
  • 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 [email protected].

    Base URLs:

    Authentication

    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:

    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.
    »» email 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 Messages. Use this endpoint to send or access direct messages to visitors.

    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.
    email 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