Introduction
Sitata's 24/7/365 emergency travel assistance is delivered through chat. When a traveller needs help β a lost passport, a medical emergency, a missed flight β they open an issue, and a live assistance agent responds in the issue's conversation.
This section explains how to build that experience into your own app or website, under your own branding, using Sitata's API and real-time socket. You can use it to build a full custom chat UI, or a headless integration that relays messages through your own systems.
info
This guide covers assistance chat only. Telemedicine (appointments, video consultations and availability bids) is out of scope.
Concepts
| Concept | What it is |
|---|---|
| Issue | An assistance case raised by (or for) a traveller. It has a type (medical, passport, flightβ¦), a status, and an optional location. Agents triage and handle issues. |
| Conversation | The chat thread attached to an issue. Every issue gets exactly one conversation, created automatically. |
| Message | A single entry in a conversation: text, an attachment, or a system announcement. |
| Participant | A user who can read and write in a conversation β the traveller, plus the agents who join to help. |
The Lifecycle At A Glance
- Get a traveller token. Chat runs as the traveller, so your app needs that traveller's own authentication token. See Authentication.
- Create an issue.
POST /api/v2/issues. The response includes theconversation_idof the auto-created conversation. See Issues. - Open the real-time socket and join
conversation:<conversation_id>. See Messaging. - Chat. Send messages over the socket, receive agent replies as they arrive, and show typing indicators and read receipts. Upload attachments and page through history over REST.
- End the case. The traveller can cancel; otherwise Sitata's agents close the case once it's resolved. If the traveller writes again, the issue reopens.
Sitata also publishes a ready-to-use JavaScript socket client β see Chat Client Reference.
Prerequisites
- An organization account with travel assistance enabled. Sitata configures which assistance provider handles your travellers' issues; contact [email protected] to set this up.
- Your organization's authentication token, kept server-side only. See API basics.
- To create travellers without sending Sitata any personal data, the Whitelabel Travellers package. See Use Privacy By Design.
Environments
| Environment | REST base URL | Socket URL |
|---|---|---|
| Production | https://www.sitata.com/api/v2 | wss://sockets.sitata.com/socket/websocket |
| Staging | https://staging.sitata.com/api/v2 | wss://staging.sitata.com/socket/websocket |