Getting Started with the REST API
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.
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 send any REST API requests from frontend (public-facing) code. The TalkJS secret key is designed to only be used in secure & controlled environments - If your secret key is exposed third parties could modify your data by making malicious REST API requests.
Authentication is performed with the "Authorization" header. Simply put your private key in the following format:
Authorization: Bearer YOUR_SECRET_KEY
Only requests with
Content-type: application/json are accepted (except for HTTP GET requests, which have no content).
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
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
The limit parameter can be added to fetching endpoints to specifcy the number of results that should be returned. e.g.
You can paginate through a list of results using the
an object ID that identifies a place in the record list. For example, if you request 10 records and the
last record's ID is
c10, then you can pass
startingAfter=c10 as an argument in order to get the next 10 results.
By default, all records are sorted in descending order based on their
createdAt property, which
is a timestamp of a record's insertion date.
The response is a json object containing a field called
data that keeps an array of requested resources.
You can send a burst of up to 600 requests before receiving
HTTP 429 Too Many Requests responses.
Over a sustained period, you can send a maximum of 9 requests per second.
These limits apply per app ID.
For more information, see the rate limiting documentation