Starting a conversation

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 field can be used to store additional metadata in the user object which can later be used in email notification templates. The values of the fields must be strings. (For more details see the reference)

Example requests to create or update two users:


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

Step 2: Create a conversation

Each conversation is uniquely identified by a unique conversation ID (e.g. order_391_fc) which can be used later as a reference to that conversation. This call can also be used to set or update the subject and custom fields of the conversation.

The subject key is optional and is used to describe the topic in a human-friendly way.
The custom fields are used to store metadata about the conversation which can later be used to filter conversations by or to be used in email notification templates. The values of the fields must be strings. (For more details see the reference)

Example request to create or update a conversation:


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

This step does not make a conversation visible to users. The Inbox only shows a conversation that contains one or more messages.

Step 3: Send a message

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:


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

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.