RTM API Reference (V1)

Updated on December 1, 2023

RTM API (Real Time Messaging API) is the principal service to listen what is happening inside an specific tenant of Talqui. Events are sent on the RTM Events API WebSocket channel that you can open alongside your REST API channel. Events are ephemeral, that way you need to garantee to listen all events as soon that occurrs, if you need to react or create any action inside yout tenant you should use REST API together.

Service

Introduction

Before you begin you need to have completed Plugin Introduction and mantain a valid plugin spec file .tal

You may subscribe to events by opening a Socket.IO connection to the WebSocket endpoint.

The RTM API endpoint URL is: wss://sock.talqui.chat/

There is a limit on the maximum number of connections that can be simultaneously open with the RTM API (per-token, per-team and per-IP). This limit is quite high and can be revised at any time. Please make sure to teardown any unused connection before opening a new one. Most use cases require a single RTM API connection.

Base Objects

Session

Session Base Object

Identifier: object:session:base
Description: Base version of session object

{
  "sessionID": "d6814578-560a-4b4b-95b8-085d465aa032",
  "contactID": "5527999999999",
  "createdAt": "2023-01-05T21:19:48.317Z",
  "operatorID": "52062885-83a7-465e-887b-3af324acebfa",
  "sessionActive": true,
  "sessionChannel": "whatsapp",
  "sessionLastMessageID": "73b8998b-b022-4a32-96a2-b1e1d927a4dc",
  "sessionMeta": {},
  "sessionRating": {
    "comment": null,
    "stars": 0
  },
  "sessionStatus": 0,
  "sessionTags": [],
  "sessionType": "manual",
  "tenantID": "db0180a1-40f4-4e03-a45f-0b7bfa6ddc9f",
  "updatedAt": "2023-01-15T03:33:38.338Z"
}

Session Extended Object

Identifier: object:session:extended
Description: Generally used over RTM API, it's an version extended of session with some id-fields already populated

{
  "sessionID": "d6814578-560a-4b4b-95b8-085d465aa032",
  "contactID": "5527999999999",
  "createdAt": "2023-01-05T21:19:48.317Z",
  "operatorID": "52062885-83a7-465e-887b-3af324acebfa",
  "sessionActive": true,
  "sessionChannel": "whatsapp",
  "sessionLastMessageID": "73b8998b-b022-4a32-96a2-b1e1d927a4dc",
  "sessionMeta": {},
  "sessionRating": {
    "comment": null,
    "stars": 0
  },
  "sessionStatus": 0,
  "sessionTags": [],
  "sessionType": "manual",
  "tenantID": "db0180a1-40f4-4e03-a45f-0b7bfa6ddc9f",
  "updatedAt": "2023-01-15T03:33:38.338Z",
  "contact": {
    "contactID": "5527999999999",
    "contactFirstname": "Cliente Acme",
    "contactLastname": "",
    "contactPhoto": null
  },
  "lastMessage": {
    "messageDirection": "inbound",
    "messageKey": "text",
    "messageValue": "Gostaria de renovar a assinatura com pagamento recorrente, é possível?",
    "messageStatus": 3,
    "messageID": "73b8998b-b022-4a32-96a2-b1e1d927a4dc"
  }
}

Events

This events below represents messages that you will receive when connected to RTM API over websocket, those messages should be listen one by one and does not have acknolodge in delivery, só it's an notification event broker

Session Events

Events that ocurrs under namespace of sessions, sessions represents an conversation between contact with a tenant, those sessions are rep

Session Change Type

Event: session:set:change_type
Description: When session change his type between auto, queued or manual

What represents each session type:

auto: Session has this state when conversation is occurring under autonomous services, like chatbot, llms or anything similar.
queued: This state only ocurrs when session is waiting to be handled by human, it's an transitory state but can be the first state when you dont have participation of chatbots in flow.
manual: Type when a session is assigned to a human, no one autonomous messages can be sent in this state.

📣 Session types queued and manual will always occur, but if you don't have any chatbot installed in a tenant where the event occurs, the type auto will be skipped. This means that the initial state of a session will be queued, indicating that the session created is waiting for human treatment since its creation.

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
  "type": "queued"
}

Session Set Routing

Event: session:set:routing
Description: Session was routed to an operator

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
}

Session Set Opened

Event: session:set:opened
Description: session was opened by some operator

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
}

Session Set Closed

Event: session:set:closed
Description: session was closed

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
}

Session Tag Added

Event: session:tag:added
Description: Session received a new tag

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
  "tag": "example"
}

Session Tag Removed

Event: session:tag:removed
Description: Session has an tag removed

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
  "tag": "example"
}

Session Rating Updated

Event: session:rating:updated
Description: Ocurrs when a session is rated by contact

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
  "stars": 5,
  "comment": "Nice treatment",
}

Session Request Initiated

Event: session:request:initiated
Description: Triggered when an a session is started by tenant with some contact

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
}

Session Summary Processed

Event: session:summary:processed
Description: Triggered when an session is summarized, event holds the session object and summarization of what was said in that session

📣 This depends of some conditions: Until today session must have more than 5 messages to be summarized. Other filters can be applied on that event avoiding to be triggered for each session. You can perform our own post-session async operations listening to event session:set:closed

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
}

Session Metadata Updated

Event: session:meta:updated
Description: This event is fired when some metadata of session was changed.

📣 Very usefull to design reactions at plugin widget, you can listen that event on backend and then trigger reactions to widget instantly, like show some information or change pages.

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "session": {
    <object:session:base>
  },
  "metaKey": "external_application_id",
  "metaValue": "12345",
}

Contact Events

Contact attributes updated

Event: contact:attributes:update
Description: Contact attributes was updated

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "contact": "4ea57339-547c-4c16-a00a-9d60f0e287c4",
  "contact": {
    <object:contact:base>
  },
}

Message Events

Message Received

Event: message:inbound
Description: Fired when a message is received at tenant

{
  "tenantID": "489e22f9-0a3a-4ac1-ab97-b7140cf61864",
  "sessionID": "7dea44ae-8f18-4991-826b-ce3b40d759d3",
  "operatorID": "72e80301-47ae-4e62-8be6-3340029ca5cb",
  "message": {
    <object:session:base>
  }
}