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 are required.
2[
3  {
4    text: string,
5    sender: string,        // sender user id
6    timestamp: number,     // in milliseconds
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  }
12]

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/conversation/5abq2/messages
2

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

Usage notes

  • 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.