Texa Desk

Bring your own channel

An API inbox connects any channel Texa Desk doesn't have (your app's chat, a kiosk, a partner's system) so your team and Texa AI answer it like any other.

An API inbox is an inbox whose messages come from your code. Customers' messages go in through the API; your team's (and Texa AI's) replies come out to your webhook. Everything else (assignment, labels, tickets, reports, Texa AI) works as in any inbox.

1. Make the inbox

In Texa Desk, Settings → Inboxes → Add inbox → API. Give it a name and, optionally, a webhook URL: where Texa Desk sends this inbox's events, so your channel can deliver replies.

The inbox's Configuration tab shows its inbox identifier, its HMAC token (for identity validation) and the webhook secret.

2. Send customers' messages in

There are two ways, depending on who holds the credentials.

From your server: the Application API

Your server, with an access token, creates the contact and conversation and posts each message as incoming:

Shell

# a conversation for a contact in the API inbox
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/conversations \
  -H "api_access_token: $TEXA_DESK_TOKEN" -H "Content-Type: application/json" \
  -d '{"inbox_id": 14, "contact_id": 345, "source_id": "kiosk-user-88"}'

# the customer's message
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/conversations/171/messages \
  -H "api_access_token: $TEXA_DESK_TOKEN" -H "Content-Type: application/json" \
  -d '{"content": "Is my card ready for collection?", "message_type": "incoming"}'

From the customer's device: the Client API

The Client API needs no secret, so an app can call it directly. It knows the inbox by its identifier and the customer by a contact identifier.

Shell

# 1. a contact (keep the source_id: it is this customer's identifier from now on)
curl -X POST https://desk.texadesk.com/public/api/v1/inboxes/$INBOX_IDENTIFIER/contacts \
  -H "Content-Type: application/json" \
  -d '{"identifier": "user-1842", "name": "Tolu Bello", "email": "[email protected]",
       "identifier_hash": "<HMAC-SHA256 of user-1842 with the inbox HMAC token>"}'

# 2. a conversation
curl -X POST https://desk.texadesk.com/public/api/v1/inboxes/$INBOX_IDENTIFIER/contacts/$CONTACT_ID/conversations

# 3. a message
curl -X POST https://desk.texadesk.com/public/api/v1/inboxes/$INBOX_IDENTIFIER/contacts/$CONTACT_ID/conversations/1/messages \
  -H "Content-Type: application/json" -d '{"content": "Is my card ready for collection?"}'

The contact identifier is the customer's key to their conversations: keep it only on their device or behind their sign-in. With identity validation on (the inbox's settings), a contact for a known identifier is created only with a valid identifier_hash, which only your server can make.

3. Deliver replies out

Every reply your team or Texa AI writes arrives at the inbox's webhook URL as message_created with message_type: "outgoing", signed with the inbox's secret (how to check). Deliver it on your channel. Skip private: true messages: they're notes for your team.

Then update its status, so your team sees whether it reached the customer: Update message status (delivered, read, failed).

Texa AI on your channel

Switch Texa AI on for the inbox like any other (Texa AI → Agent and inboxes). It answers in the inbox, and its replies reach your webhook the same way. If you only want Texa AI and no helpdesk around it, the Texa API is simpler.