Messages

You can programmatically send messages on behalf of a user in a conversation. The behavior is identical to that when sending messages via the UI; notifications are triggered based on the participating user's role. UserMessage also supports sending attachments and locations. See Sending Files.

1[
2  {
3    text: string
4    sender: string
5    type: "UserMessage"
6    referencedMessageId?: string
7    custom?: { [key: string]: string }
8    idempotencyKey?: string
9  },
10  ...
11]

1[
2  {
3    "text": "Meet me outside",
4    "sender": "123143551",
5    "type": "UserMessage",
6    "referencedMessageId": "msg_6TKoWs0Jm8XrjPOmFdOGiX"
7  }
8]

sender has to be a participant in the conversation. type must be "UserMessage" when sender is provided or the request fails.

The referencedMessageId property is used when the message you are sending is meant to be a reply to another message.

System messages are messages which are not sent by a participant, but programmatically by your application. A SystemMessage is displayed differently in the UI, and doesn't trigger notifications for any user in the conversation. You are expected to handle these notifications in your application if needed. These messages support attachments but don't currently support locations.

System Messages support formatting.

Some example use cases in a marketplace for System Messages are 'order received' and 'payment failed', but these can be anything from payment confirmations to "User left the group" notifications.

1[
2  {
3    text: string
4    type: "SystemMessage"
5    custom?: { [key: string]: string }
6    idempotencyKey?: string
7  },
8  ...
9]

1[
2  {
3    "text": "Purchase Complete",
4    "type": "SystemMessage"
5  }
6]

text field supports the same syntax as Subjects. sender must not be provided when sending system messages.

If an initial request fails, you may want to retry the request. To avoid message duplication on retries, you can use the idempotencyKey field when sending the message. If you use an idempotencyKey, you can try a request any number of times and TalkJS guarantees that the message gets sent exactly once.

Make sure that the idempotencyKey you use is unique within the conversation in which the message is sent. If two messages in the same conversation have the same idempotencyKey, the system treats those two messages as if they're the same request, and only the first message with that idempotencyKey gets processed.

TalkJS associates a message with an idempotencyKey for 24 hours. After 24 hours, the idempotencyKey expires and you can reuse the key for a different message.

Similarly to other list requests, pagination and limits are applicable to listing messages.

1GET https://api.talkjs.com/v1/{appId}/conversations/{conversationId}
2GET https://api.talkjs.com/v1/{appId}/conversations/{conversationId}?limit=50
3GET https://api.talkjs.com/v1/{appId}/conversations/{conversationId}?startingAfter=c_21
4GET https://api.talkjs.com/v1/{appId}/conversations/{conversationId}?startingAfter=c_21&limit=10

You upload a file using the files endpoint:

1{
2    "attachmentToken": "L0oQOg5DVENGFVQZABpOQVNRCxs...EFFbHxhiXVEYUBw"
3}

This is the only resource on the TalkJS REST API that does not accept a JSON payload. Instead, send multipart/form-data formatted data with two required parameters:

1. file - This is the file data you want to upload.
2. filename - The name of the file.

This is the usual way files are uploaded over HTTP. Check the docs of your favorite HTTP client for information on how to upload files with it. For example: JavaScript, Python (Requests), PHP, Ruby (RestClient).

This endpoint returns a JSON object with a single property, attachmentToken.

Now, use the usual messages resource to send a message, but replace the text field by an attachmentToken field:

1[
2  {
3    attachmentToken: string,
4    sender: string,
5    type: 'UserMessage',
6  },
7];

Alternatively, images can be sent using a system message by omitting the sender and using SystemMessage as the message type.

1[
2  {
3    attachmentToken: string,
4    type: 'SystemMessage',
5  }
6]