Skip to main content

Notifications & Webhooks

Travellers aren't always looking at the chat when an agent replies. This page explains how they're told about new activity, and how you can take over those notifications under your own brand.

While The App Is Open

If your app keeps a socket connected while the traveller is elsewhere in the app, you can join their personal notification topic and show in-app alerts:

TopicEventPayload
notification:<user_id>notification:new{"notification": {"id", "type", "title", "body", "data", "created_at", ...}}

The notification types relevant to chat are listed below. Their data carries a conversation_id, so you can deep-link straight to the chat.

To show an unread badge without a socket, poll GET /api/v2/issues/unread_count ({"unread_count": 3}), or read the per-issue unread_count from GET /api/v2/issues.

When The App Is Closed

By default, Sitata notifies the traveller itself by push notification and email. For example, when an agent's message goes unread for about 15 seconds while the traveller isn't connected, Sitata sends a "New message from โ€ฆ" notification. Repeat notifications for the same conversation are throttled.

TypeNameSent when
5Missed conversation messageA message arrives while the traveller isn't connected to the conversation.
6New conversationThe traveller is added to a new conversation.
9Inactive issueAn open issue has had no activity for 6 days. It will be finished automatically the next day.
10Finished issueAn issue was finished automatically after 7 days without activity.

Sitata's push notifications reach only Sitata's own apps. If your travellers use your app, you'll want to deliver these notifications yourself, using the whitelabel webhooks below.

Whitelabel: Deliver Notifications Yourself

If your organization has the Whitelabel Travellers package, which anonymous travellers require, Sitata does not contact your travellers directly. Instead, every notification that would have been sent fires a notification.suppressed webhook to your servers, and you relay it to the traveller under your own brand, for example as a push notification in your app.

Register a webhook endpoint and subscribe to the chat notification types:

POST /api/v2/org/:company_id/webhook_endpoints
{
"webhook_endpoint": {
"enabled": true,
"url": "https://www.your-company.co/webhooks/sitata",
"enabled_events": [5, 6, 9, 10]
}
}

Each delivery's event is the notification type. Its payload contains the notification and a PII-free user object, including your own external_id:

{
"event": 5,
"event_name": "notification.suppressed",
"notification": {
"id": "...",
"type": 5,
"title": "New message from Maria",
"body": "We've found the nearest consulate. Can you get to ...",
"data": { "conversation_id": "a4e2c1d7-9b8f-4e6a-b5c3-1d2e3f4a5b6c", "recipient_role": "user" },
"created_at": "2026-10-12T14:09:42Z"
},
"user": { "id": "6b0c6f8e-...", "external_id": "customer-8842", ... }
}

Match user.external_id to your customer, and use data.conversation_id to open the right chat when they tap the notification.

Webhook deliveries are signed and retried. Verify the Sitata-Signature header as described in Verify the signature.

info

There are no webhook events for every new issue or message. Webhooks only fire for notifications Sitata would have sent to a traveller. To follow a conversation in real time, use the socket.

Monitoring Your Organization's Issues

From your back office, you can list the issues and conversations that belong to your organization (see Which Token Can Call What) with your organization token:

GET /api/v2/org/:company_id/issues
GET /api/v2/org/:company_id/conversations

Staff users with travel-manager access to your organization can also subscribe to company-issues:<company_id> on the socket, which broadcasts issues:new_issue and issues:updated_issue with the full issue. Organization tokens cannot connect to the socket, so this needs a staff user's token.