# Agent bots

Your own bot in Texa Desk: it gets each conversation's events, answers through the API, and hands over to your team.


An **agent bot** is a bot you host. Texa Desk sends it the events of the inboxes it's connected to;
it answers through the Texa Desk API with its own token, and hands the conversation to people by
opening it. This is how anyone can put their own automation in front of a team.

!!! tip "Texa AI already does this"
    Texa AI is Texa Desk's own agent, with procedures, actions and handover built in. Build an agent
    bot when you need logic of your own: a menu for a kiosk, a partner's bot, a rules engine.

## 1. Create the bot

In Texa Desk, **Settings → Bots → Add bot**: a name, an avatar and the **webhook URL** where it
receives events. The bot gets an **access token**. Or create it with the API:
[Create an agent bot](/api-reference/desk/account-agent-bots/create-an-agent-bot).

Then connect it to an inbox: the inbox's settings → **Bot configuration**, or
[Add or remove agent bot](/api-reference/desk/inboxes/add-or-remove-agent-bot).

## 2. What the bot receives

| Event | When |
|---|---|
| `message_created` | a message in one of its conversations |
| `message_updated` | a message changed |
| `conversation_opened` | a conversation opens (or reopens) |
| `conversation_status_changed`, `conversation_updated` | its status or attributes change |
| `conversation_resolved` | it's resolved |
| `webwidget_triggered` | a visitor opened the live chat on your website |

The payloads are the same as [Texa Desk webhooks](/guides/desk-webhooks#what-arrives). While a bot
is connected, new conversations start as **pending**: they're the bot's until it hands them over.

## 3. Answer

Reply with the bot's token in `api_access_token`:

```bash
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/conversations/171/messages \
  -H "api_access_token: $BOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"content": "Your card is ready at our Lekki branch.", "message_type": "outgoing"}'
```

Only reply to `incoming` messages, so the bot never answers itself.

## 4. Hand over to people

Set the conversation **open**, and Texa Desk assigns it to your team as usual:

```bash
curl -X POST https://desk.texadesk.com/api/v1/accounts/1/conversations/171/toggle_status \
  -H "api_access_token: $BOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"status": "open"}'
```

A bot's token can also change priority, typing status and assignment, but only on the conversations
of its own inboxes.

## When the bot fails

If the bot's webhook answers an error or doesn't answer, Texa Desk opens the pending conversation for
your team, so a customer is never left waiting on a broken bot. An account can choose to keep such
conversations pending instead.