Get started with the REST API

https://api.talkjs.com

The TalkJS REST API has read/write access to all data in your TalkJS account. Therefore you need to use a token with access to all data in your TalkJS account.

Since these tokens are so powerful, we recommend generating single-use tokens. Your server should generate a new token for each REST API request. That means the tokens can use an extremely short expiry time, so that even if you accidentally leak a token, it will expire before anyone can exploit it.

Generating a REST API token that expires after 30 seconds:

1// Uses `jsonwebtoken`: https://www.npmjs.com/package/jsonwebtoken
2import jwt from 'jsonwebtoken';
3
4const encoded_jwt = jwt.sign({ tokenType: 'app' }, '<SECRET_KEY>', {
5  issuer: '<APP_ID>',
6  expiresIn: '30s',
7});
8console.log(encoded_jwt);

Authentication is performed with the Authorization header. Provide your token in the following format:

Authorization: Bearer <YOUR_TOKEN>

For example:

1fetch('https://api.talkjs.com/v1/<APP_ID>', {
2  headers: {
3    Authorization: 'Bearer ' + generateToken(),
4  },
5});

The technical name for these tokens is "app-scoped" tokens. You can read more about the tokens used by TalkJS in our authentication reference.

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 wasn't correct, to be more precise:

• 400 means that the arguments passed weren't correct
• 401 means that the "Authorization" header with the token wasn't present or was incorrect.
• 404 means that the resource couldn't 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. Don't inspect the response body for determining this.

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

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.

The limit parameter can be added to fetching endpoints to specify the number of results that should be returned, for example: ?limit=20.

• When fetching Conversations limit must be a number between 1 and 30. The default limit is 10.
• When fetching Users or Messages limit must be a number between 1 and 100. The default limit is 10.

You can paginate through a list of results using the startingAfter cursor. startingAfter is 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 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, or 1 batch request per second. These limits apply per app ID.

For more information, see the rate limiting documentation.