Authentication
Assistance chat uses two kinds of credentials:
- Your organization token, which identifies your company. Keep it on your servers and never ship it to a browser or mobile app.
- A traveller token, which identifies one traveller. This is what your client app uses to create issues, chat, and connect to the real-time socket.
Most chat operations are performed as the traveller. An organization token can create and view your organization's issues and read their conversations, but it cannot send messages, open the socket, or cancel an issue on a traveller's behalf.
1. Get A Traveller Token
Create (or look up) the traveller from your server using your organization token. Each of these endpoints returns a user profile that includes an authentication_token:
| Endpoint | Use when |
|---|---|
POST /api/v2/org/:company_id/users/anonymous | You don't want to share personal data. Pass only your own external_id. Idempotent: calling it again returns the same traveller. Requires the Whitelabel Travellers package. See Use Privacy By Design. |
POST /api/v2/org/:company_id/users/travellers | You register travellers with their details. See Create a Traveller. |
curl -X POST https://www.sitata.com/api/v2/org/$COMPANY_ID/users/anonymous \
-H "Authorization: TKN $ORG_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id": "customer-8842"}'
{
"id": "6b0c6f8e-2b1f-4a8e-9d55-0d6f1d3c2a10",
"external_id": "customer-8842",
"anonymous": true,
"authentication_token": "3f1c9a52-7c2e-4b7e-a1f0-5d9e8b6c4a21",
...
}
Store the traveller's id and authentication_token with your customer record, and hand the token to your client app once the customer is signed in to your platform.
2. Call The API As The Traveller
Send the traveller token in the Authorization header and your company id in the Organization header on every request:
Authorization: TKN <traveller authentication_token>
Organization: <company_id>
The Organization header matters for chat: it tells Sitata which organization the traveller is acting under, so their issues go to the assistance provider configured for your organization rather than to Sitata's default team.
3. Get A Socket Token
The real-time socket takes its own signed token. Request one as the traveller:
curl -X POST https://www.sitata.com/api/v2/tokens/for_socket \
-H "Authorization: TKN $TRAVELLER_TOKEN" \
-H "Organization: $COMPANY_ID"
{ "token": "SFMyNTY.g2gDbQAAACQ2YjBjNmY4ZS0yYjFm..." }
Socket tokens are valid for 7 days. Request a fresh one whenever you (re)connect rather than storing it. Organization tokens cannot request a socket token.
Which Token Can Call What
| Action | Endpoint | Traveller token | Organization token |
|---|---|---|---|
| Create an issue (recommended) | POST /issues | โ | โ |
| Create an issue for a traveller | POST /org/:company_id/issues | โ | โ |
| List the traveller's issues | GET /issues | โ | โ |
| List your organization's issues | GET /org/:company_id/issues | โ | โ |
| View an issue | GET /issues/:id | โ | โ |
| Cancel an issue | PATCH /issues/:id/cancel | โ | โ |
| Change an issue's status or close it | Sitata assistance agents only | โ | โ |
| Read an issue's conversation | GET /issues/:id/conversation | โ | โ |
| Page through a conversation's messages | GET /conversations/:id/messages | โ | โ |
| Send a message / upload an attachment | POST /conversations/:id/messages | โ | โ |
| Get a socket token | POST /tokens/for_socket | โ | โ |
Organization access is limited to issues that belong to your organization, which are the issues you create with the organization endpoint. Issues a traveller creates themselves are visible to that traveller and to Sitata's assistance team.
Changing an issue's status, including closing it, is reserved for Sitata's assistance agents. Travellers can cancel their own issues.