Call the TalkJS REST API in order to manage messages, conversations and users from your backend. The API is REST-based, using HTTP and JSON. The API only accepts authenticated calls over HTTPS, and uses HTTP status codes for reporting results.

Authentication

Authenticate your account when using this API by including the secret key in the request. You can see your secret API key in the dashboard. Do not share private keys with anyone else and don't use them in your frontend code. They are intended to be used only from your server-side application.

Authentication is performed with the "Authorization" header. Simply put your private key in the following format:

Authorization: Bearer YOUR_SECRET_KEY

Content Type

Only requests with Content-type: application/json are accepted (except for HTTP GET requests, which have no content).

Return values

TalkJS uses HTTP status codes to indicate whether the request was fine or not. TalkJS always returns HTTP status 200 if a request was processed successfully.

Statuses 4xx mean that the user input was not correct, to be more precise:

• 400 means that the arguments passed were not correct
• 401 means that the "Authorization" header with the token was not present or was incorrect.
• 404 means that the resource could not be located.

Very rarely, TalkJS may return status 5xx, indicating that something went wrong on the TalkJS servers. This may indicate a bug in TalkJS, but it might also be unexpected downtime. Treat this as you would a connection error; you can safely retry this operation.

The HTTP status code is the only way to verify whether a call was successful. Do not inspect the response body for determining this!

All API responses are JSON. Even calls that return no data have a {} response.

Listing

Most of our resources have support for "listing". You can list users, conversations or messages. They all share the same response structure and the same arguments. It accepts common parameters like limit and startingAfter.

Limits

The limit parameter can be added to fetching endpoints to specifcy the number of results that should be returned. e.g. ?limit=20

• When fetching Conversations limit must be a number between 1 and 20 (defaults to 10, if not passed).
• When fetching Users or Messages limit must be a number between 1 and 100 (defaults to 10, if not passed).

Pagination

startingAfter is a cursor that is used in pagination. All records are sorted descendigly and startingAfter indicates an object ID that defines place in the list. For example if you request 10 records and the last record has an ID c10, you have to pass staringAfter=c10 as an argument in order to get next 10 results.

Response

The response is a json object containing a field called data that keeps an array of requested resources.

Rate limits

The REST API accepts bursts of up to 530 requests in a short period of time, but generally request rates should not exceed more than 8 requests per second. If the limit is exceeded for a sustained amount of time, requests will return a HTTP 429 "Too many requests" response, indicating you need to retry the request later.

Need this limit increasing? Let us know

Troubleshooting

If your REST requests yield funky errors, try one of these:

I'm getting a "cookies required" error but the same request works with cURL or Postman.

Check whether you're sending a "User-Agent" header. Most languages and libraries do this automatically, but some (eg Java) do not. Try setting this header manually. The value does not matter.

I'm getting SSL / certificate errors

Some customers have reported that this happens on outdated cacert files. Update your trusted certificates to a later version.