One common use of the REST API is to start a conversation between two users from the backend before either user has loaded TalkJS in their browsers. This guide will explain how.

In order to start a conversation with the REST API, you need to do the following steps:

Step 1: Synchronize user data.

This step is necessary to update users data in TalkJS. The url structure is the following: /v1/{appId}/users/{userId}. For the userId choose a value that will not change in your database (the primary key of your user). name and email are the minimum amount of data that you need to pass. The custom fields are used to put your metadata in the user object, so that you can reuse it later in the configurable email templates or in webhook handlers. The values of the fields must be strings. (For more details see the reference)

Example requests to synchronize two users:

curl https://api.talkjs.com/v1/YOUR_APP_ID/users/12081 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X PUT \
-d '{ "name":"Alice", "email": ["[email protected]"], "photoUrl": "https://yoursite.com/userpictures/12081.png", "welcomeMessage": "Hey there! :-)", "configuration": "buyer" }'

curl https://api.talkjs.com/v1/YOUR_APP_ID/users/8029 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X PUT \
-d '{ "name":"Bob", "email":["[email protected]"], "photoUrl":"https://yoursite.com/userpictures/8029.png", "welcomeMessage":"Hey there! :-)", "configuration":"seller", "custom": { "birthday": "1487842094224" } }'

Step 2: Set the conversation subject and custom fields.

To identify your conversation use one of patterns described in the Reference. This call can be used to update the subject or custom fields of the conversation. The subject key is optional and should describe the topic in a human-friendly way. The custom fields are used to put your metadata in the conversation, so that you can reuse it later in the configurable email templates or in webhook handlers. The values of the fields must be strings. (For more details see the reference)

Example request to synchronize the conversation:

curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X PUT \
-d '{ "participants": ["12081", "8029"], "subject": "What a lovely day!", "custom": { "specialToken": "h193nduahf" } }'

This step does not make a conversation visible to users. Users only see a conversation in which they have sent or received at least one message.

Step 3: Send messages.

In order to send messages as one party to someone else, you need to pass an array of messages. In most cases you will send just one message in the array, but if you want to send more, add them to the array. This ensures that the order is correct. (For more details see the reference). Example request to send messages:

curl https://api.talkjs.com/v1/YOUR_APP_ID/conversations/order_391_fc/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X POST \
-d '[{ "text": "Hello Alice!", "sender": "8029", "type": "UserMessage" }]'

The conversation is uniquely identified by participants and topic. Steps 1 and 2 are idempotent, meaning that you don't have to worry calling the endpoint too many times. You can read more information about conversations here.