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

Path: /v1/{appId}/import/conversations/{conversationId}/messages
Methods:POST
Payload: [{
  text: string,
  sender: string, // sender user id
  timestamp: number, // in milliseconds
  readBy: Array, // a list of user ids who have read the message
  type: "UserMessage"
}]

All fields are required.

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"]
  }
]

Usage notes

  • Duplicates are not removed. If you send the same message twice, they will show up twice, even if they have the same timestamp.
  • 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 that you try your import your real production data on the TalkJS test app until it works. While testing your import, you can use the "Reset all data" button in the dashboard to delete everything if something goes wrong (this button is not available in the live app)