Import messages

You can import data from any existing messaging system into TalkJS using the REST API.

To import existing data, you need to send TalkJS three kinds of data: users, conversations, and messages. Users and conversations are 'timeless' resources, which you can import using the normal REST API endpoints. For importing messages with timestamps, you can use a special importing resource.

Make your import script follow these steps, in order:

  1. Import all users with the User resource.
  2. Import all conversations with the Conversation resource.
  3. Import all messages with the Import messages resource.

Import messages resource

POST/v1/{appId}/import/conversations/{conversationId}/messages
1// All fields except `attachmentToken`, `custom` and `referencedMessageId` are required.
2[
3  {
4    text: string,
5    sender: string,        // sender user id
6    createdAt: number,     // in milliseconds since epoch (formerly known as 'timestamp')
7    readBy: Array<string>, // a list of user ids who have read the message
8    type: "UserMessage",
9    attachmentToken?: string, // optionally specify a message attachment
10    custom?: {[name: string]: string },
11    referencedMessageId?: string; // optionally specify the ID of a message this one refers to
12  }
13]

For example, if you have a conversation with id abcdef with two participants, user 1234 and user 5678, then you could import two messages into this conversation as follows:

1POST https://api.talkjs.com/v1/YOUR_APP_ID/import/conversations/5abq2/messages
2

3[
4  {
5    "text": "Hello!",
6    "sender": "1234",
7    "createdAt": 1509132622706,
8    "type": "UserMessage",
9    "readBy": ["5678"]
10  },
11  {
12    "text": "Well hi there, how are you?",
13    "sender": "5678",
14    "createdAt": 1509132692706,
15    "type": "UserMessage",
16    "readBy": ["1234"],
17    "attachmentToken": "L0oQOg5DVENGFVQZABpOQVNRCxs...EFFbHxhiXVEYUBw"
18  }
19]

Handling referencedMessageId

When importing messages that reference other messages (referencedMessageId), ensure that you have completed importing the batch of messages that may contain the referenced IDs before starting a new batch with messages that include referencedMessageId. This procedure involves retrieving the newly assigned message IDs from the response of the previous batch, and then using these IDs in your subsequent import requests.

Usage notes

  • The maximum amount of messages sent in one request is 1000.
  • To import messages with attachments, first upload the file, then specify the attachment token when importing the message.
  • Currently you can only import messages sent by conversation participants. You can't import system messages or messages sent by guests.
  • Duplicate messages aren't removed. If you sent or imported the same message twice, it shows up twice, even if the messages have the same timestamp.
  • Notifications aren't sent for imported messages. Changes due to importing messages aren't synchronized back to active clients. If a user is currently reading a conversation that you're importing messages into, they need to reload before they see the imported messages.
  • Import your data into the TalkJS test mode first to check if everything works as expected, before you import your data into live mode. If anything goes wrong while testing your import, you can use the Reset all data button on the Settings page of your dashboard to irrevocably delete all messages, conversations, and users.