Instaply Bot API

The Instaply BOT API is based on a set of API and a webhook mechanism.

Every request to the API should have in the headers a token field with your API key as value, and a Content-Type with value application/json

Your token is associated to a user in the Instaply UI, and you can only modify threads to which this user has access.

Send Messages API

Located at: https://me.instaply.com/api/send-message-to-customer-thread

The API is quite simple: it works using a POST request with a json body, and you should specify in the body, a json dictionary with three fields:

• text: the textual content of your message
• customerThreadId: the id of the customer thread that your are trying to send a message to.
• internal: a boolean value specifying if your message should be posted in the public part of the customer thread, or in the collaboration thread (the "invisible" part).

This for example is a valid way to do a request from the command line on Mac or Linux.

 curl -X "POST" "https://me.instaply.com/api/send-message-to-customer-thread" \
    -H "token: your-token-here" \
    -H "Content-Type: application/json" \
    -d "
    {\"text\":\"Hello, I am a bot. \",\"customerThreadId\":\"9999\"}
 "

Update thread status

Located at: https://me.instaply.com/api/update-thread-status

This method allows to change the status of a thread. The json body should contain two fields:

• customerThreadId: the id of the customer thread for which you want to change the status.
• status: a string field, with only three possible values: 'waiting', 'replied' and 'resolved'

Example request:

 curl -X "POST" "https://me.instaply.com/api/update-thread-status" \
      -H "token: your-token-here" \
      -H "Content-Type: application/json" \
      -d $'{
   "status": "waiting",
   "customerThreadId": "12345"
 }'

Edit your organization webhook url

This endpoint allows you to edit the url of the webhook that our backend is calling on every message of your organization(see the Web hook section)

There is only one field to specify in the json body:

• url: the url of where you want our backend to make a callback on every new message

Example request:

     curl -X "POST" "https://me.instaply.com/api/update-hook-url" \
        -H "token: your-token-here" \
        -H "Content-Type: application/json" \
      -d $'{"url": "http://example.com/instaplybot"}'

Web hook

You can provide us a URL where our backend will forward the content of all messages sent in a customer thread (hence, not messages used in a conversation between employees, so far).

Once we setup this URL, for every message, our backend will attempt to POST a JSON object similar to the following:

{
    "customerId":"148332",
    "customerThreadId":156100,
    "messageTimestamp":1484768843336,
    "employeeUserId":7889,
    "messageId":4683951,
    "messageBody":"Yep, it works",
    "businessId":907,
    "messageAttachmentName":null,
    "messageAttachmentContentType":null,
    "messageAttachmentUUID":null,
    "messageAttachmentContentLength":null,
    "fromCustomer": false,
    "messageExternalId": null,
    "invisible": false,
    "customerType":"prospect"
}

Most fields are self explanatory, but for the others, here is a bit of information:

• customerThreadId is the id of the customer thread. This is the id that you have to specify in the send API if you want to send a message to the customer (or to colleagues, in the invisible thread).
• employeeUserId is the id of the employee who sent the message.
• fromCustomer is a boolean that is true if the message was written by a customer and not by an employee
• invisible is a boolean that is true if the current message was sent in the invisible (employee-only) part of the customer thread.
• customerType should right now always have the value prospect.