Bot API

To allow integration with third party services like bots or CRMs, Instaply offers an API to developers. Ask an access to that API to your customer representative, who will be able to provide you the API keys that you will need to setup an API integration with Instaply.

 

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"}'

NOTE: This is the old endpoint when only allow one webhook per organization. We kept backward compatibility but right now is adding always a new webhook. We strongly recommend to use the new following endpoints allow to manage the multiple webhooks

get-hook-query (GraphQL)

This GraphQL endpoint allows to query and get the webhook list configured per organization.

 

Request fields

Those are the variables to specify in the JSON body:

Response (data/hook)

A GraphQL JSON response listing all webhook of your organization, with the following fields:

Example #1

• Request

curl -s -X "POST" "https://me.instaply.com/graphql" \
    -H "token: <your-token-here>" \
    -H "Content-Type: application/json" \
    -d '{ "query": "get-hook-query" }'

• Response

{
  "data": {
    "hook": [
      {
        "hookId": "1",
        "url": "http://www.instaply3.tv",
        "enabled": false
      },
      {
        "hookId": "2",
        "url": "http://example.com/instaply/robot/1",
        "enabled": true
       }
    ]
  }
}

Example #2

• Request

curl -s -X "POST" "https://me.instaply.com/graphql" \
    -H "token: <your-token-here>" \ -H "Content-Type: application/json" \ -d '{ "query": "get-hook-query", "variables": { "hookId": [ "2" ] } }'

• Response

{
  "data": {
    "hook": [
      {
        "hookId": "2",
        "url": "http://example.com/instaply/robot/1",
        "enabled": true
       }
    ]
  }
}

save-hook-mutation (GraphQL)

This GraphQL endpoint allows to create or update a webhook for your organization.

Request fields

Those are the variables to specify in the JSON body:

Response (data/saveHook)

A GraphQL JSON response with the configured webhook with the following fields:

Example #1

• Request

curl -s -X "POST" "https://me.instaply.com/graphql" \
    -H "token: <your-token-here>" \ -H "Content-Type: application/json" \ -d '{ "query": "save-hook-mutation", "variables": { "hookId": "666", "url": "http://example.com/instaply/robot/1", "enabled": true } }'

• Response

{
  "data": {
    "saveHook": {
      "hookId": "666",
      "url": "http://example.com/instaply/robot/1",
      "enabled": true
    }
  }
}

Example #2

• Request

curl -s -X "POST" "https://me.instaply.com/graphql" \
    -H "token: <your-token-here>" \ -H "Content-Type: application/json" \ -d '{ "query": "save-hook-mutation", "variables": { "hookId": "666", "enabled": false } }'

• Response

{
  "data": {
    "saveHook": {
      "hookId": "666",
      "url": "http://example.com/instaply/robot/1",
      "enabled": false
    }
  }
}

delete-hook-mutation (GraphQL)

This GraphQL endpoint allows to delete one or more webhooks configured per organization.

Request fields

Those are the variables to specify in the JSON body:

Response (data/deleteHook)

A GraphQL JSON response have following fields:

Example #1

• Request

curl -s -X "POST" "https://me.instaply.com/graphql" \
    -H "token: <your-token-here>" \ -H "Content-Type: application/json" \ -d '{ "query": "delete-hook-mutation", "variables": { "hookId": ["2", "666"] } }'

• Response

{
  "data": {
    "deleteHook": {
      "flag": true
    }
  }
}

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.