# 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`:

```bash
# 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](/api-reference/client) needs no secret, so an app can call it directly. It knows
the inbox by its identifier and the customer by a contact identifier.

```bash
# 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": "tolu@example.com",
       "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](/guides/desk-webhooks#check-the-signature)). 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](/api-reference/desk/messages/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](/quickstart) is simpler.