Importing Messages

If you have an existing messaging system that you'd like to replace with TalkJS, then you can use our REST API for importing.

To import existing data, you need to send three kinds of data to TalkJS: Users, Conversations and Messages. Users and Conversations are relatively "timeless" resources, so you can just import them using our normal REST API endpoints. For importing messages we have a special importing resource that works a little differently.

Therefore, we recommend that you 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 Imported Messages resource, described below.

Importing messages

POST/v1/{appId}/import/conversations/{conversationId}/messages
// All fields are required.
[
  {
    text: string,
    sender: string,        // sender user id
    timestamp: number,     // in milliseconds
    readBy: Array<string>, // a list of user ids who have read the message
    type: "UserMessage",
    attachmentToken?: string, // optionally specify a message attachment
    custom?: {[name: string]: string };
  }
]

For example, imagine a conversation with id abcdef with 2 participants, user 1234 and user 5678. You could import 2 messages into this conversation as follows:

POST https://api.talkjs.com/v1/YOUR_APP_ID/import/conversation/5abq2/messages


[
  {
    "text": "Hello!",
    "sender": "1234",
    "timestamp": 1509132622706
    "type": "UserMessage",
    "readBy": ["5678"]
  },
  {
    "text": "Well hi there, how are you?",
    "sender": "5678",
    "timestamp": 1509132692706,
    "type": "UserMessage",
    "readBy": ["1234"],
    "attachmentToken": "L0oQOg5DVENGFVQZABpOQVNRCxs...EFFbHxhiXVEYUBw"
  }
]

Usage notes

  • To import messages with attachments, first upload the file, then speicfy the attachment token when importing the message.
  • Currently it is only possible to import messages that were sent by conversation participants. System messages and messages sent by guests are not supported.
  • Duplicate messages are not removed. If you send the same message twice, they will show up twice, even if they have the same timestamp. This includes running your import script twice.
  • None of the typical things TalkJS does when sending messages happens. E.g. no emails are sent and no changes are synchronized back to active clients. If any user is currently looking at a conversation that you're importing messages into, they may need to reload before they see them.

We strongly recommend importing your production into the TalkJS test mode first, and checking it works as expected before importing your data to live mode. While testing your import, you can use the "Reset all data" button in the dashboard to delete everything if something goes wrong.