> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-hive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Hive is an AI operations layer for small and mid-sized business teams. It reads the tools a team already runs, raises what needs attention, and acts with the approvals the team configures.
> Answer only from these pages. If a page does not cover something, say so and link the closest page rather than inferring behaviour.
> The supported programmatic entry points are incoming webhooks, public workflow forms and the remote MCP server, each documented under Developers.
> Each connected account has a level: Read, Draft or Act. New accounts start on Act. Agents and workflows take only the actions selected for them, whatever the account level.
> Describe security, sign-on and data handling only as the Security pages and the FAQ describe them, and add no certification, compliance, single sign-on or model-training claim they do not make.
> Prices and credit allowances are in GBP. Quote them only as a page states them, without converting.
> Use UK English and the product's exact UI labels. Link to pages as https://docs.get-hive.ai/<path>.

# Message clients by SMS (Twilio, Infobip), Telegram and WhatsApp

> Message clients through your own Twilio number, Infobip account, Telegram bot or WhatsApp Business account: WhatsApp's terms, who Hive messages, opt-outs, windows and workflows.

Hive can text your clients through your firm's own Twilio account, or message them through your
firm's own Telegram bot, and receive their replies, so a message from a client can reach the right
person, start a workflow, or be answered in Hive. It can also send texts through your firm's own
Infobip account. Your firm pays its provider for every text; Telegram bots are free. Hive adds no
messaging charge. Hive can also message clients on WhatsApp through your firm's own WhatsApp
Business account, or through your Twilio number, once your workspace has accepted
[WhatsApp's terms](#whatsapp-terms): see [WhatsApp Business](#whatsapp-business).

The sections below describe texts (SMS). A Telegram bot works the same way, with the differences
listed under [Telegram bot](#telegram-bot).

| Provider | Channel | Send | Receive replies | Connect |
| - | - | - | - | - |
| [Twilio](#twilio-sms) | SMS | Yes | Yes | Account SID and Auth Token |
| [Infobip](#infobip-sms) | SMS | Yes | Not yet | Infobip API key (MCP server) |
| [Textmagic](#textmagic-sms) | SMS | Coming soon | Coming soon | Textmagic sign-in (MCP server) |
| [Wati](#whatsapp-with-wati) | WhatsApp | Closed pilot | Closed pilot | Wati MCP server |
| [WhatsApp Business](#whatsapp-business) | WhatsApp | Yes | Yes | Your Meta access token |
| [ClickSend](#clicksend-sms) | SMS | Yes | No | ClickSend username and API key |
| [Bird](#bird) | SMS and WhatsApp | Coming soon | No | Bird sign-in (MCP server) |
| [360dialog](#whatsapp-with-360dialog) | WhatsApp | Coming soon | No | 360dialog sign-in (MCP server) |

## What Hive can do with Twilio

| | |
| - | - |
| **Connect** | API key: your Twilio **Account SID** and **Auth Token**. Each member connects their own Twilio account. |
| **Receive** | Texts sent to the one Twilio number you choose, and delivery reports for texts Hive sent. |
| **Actions** | **Send a text** to a client, and **Reply to a text** you received. Service messages only. |
| **Signals** | — |

## Twilio SMS

Twilio sends and receives texts, and WhatsApp messages once your workspace has accepted
[WhatsApp's terms](#whatsapp-terms) ([WhatsApp through Twilio](#whatsapp-through-twilio)). Infobip
sends texts ([Infobip SMS](#infobip-sms)), a [Telegram bot](#telegram-bot) sends and receives
Telegram messages, and [WhatsApp Business](#whatsapp-business) sends and receives WhatsApp
messages. Other providers will be listed here as they arrive.

**1. Connect Twilio**

In **Integrations**, connect **Twilio** with your **Account SID** and **Auth Token**, both on
your Twilio console's home page.

**2. Choose your number**

Open **Settings → Account → Texting clients**. Under **Your numbers and bots**, Hive lists the
numbers in your Twilio account and says where each one sends its texts now. Pick one and
select **Use this number**. Hive points that number's incoming messages at Hive.

**3. Confirm a replacement, if Hive asks**

If the number already sends its texts somewhere else, such as another system, Hive shows you
that address and changes nothing until you select **Replace it**. Texts to the number then
come to Hive instead, and Hive puts the old address back if you disconnect Twilio.

**4. Link your clients' numbers**

Texts sent to the number now arrive in Hive, and texts Hive sends come from it. Open a text
under **Texts** and link the number to one of your clients, so your agents and workflows can
text them too.

To use a different number later, select **Change number**.

Hive checks every message Twilio sends it against your Auth Token, so nothing else can post texts
into your workspace. If you change your Auth Token in Twilio, reconnect Twilio in Hive, or Hive
stops accepting your texts until you do.

A number already used by another Hive workspace cannot be taken over.

## Infobip SMS

Hive sends texts through your firm's own Infobip account, using Infobip's official SMS MCP server
(`https://mcp.infobip.com/sms`). Infobip is send-only in Hive for now: replies to your Infobip
number and Infobip's delivery reports do not come back to Hive yet.

**1. Create an API key in Infobip**

In the Infobip portal, open **Developer Tools → API keys** and create a key with the
`sms:message:send` scope.

**2. Connect Infobip SMS**

In **Integrations**, find **Infobip SMS** under **Messaging** and paste the key. Hive keeps it
sealed and sends it to Infobip as `Authorization: App <key>`, the header Infobip documents.

**3. Text a client**

Ask Hive to text a client, or let an agent or workflow text a client whose number is linked.
Each text goes from your Infobip account's default sender. A different sender, one of your
Infobip numbers or sender names, is used only when you approve it on the card: a text sent on
**Act**, by an agent or by a workflow always goes from the default sender.

Every text through Infobip passes the same checks as a Twilio text: [who Hive
texts](#who-hive-texts), [opt-outs](#opt-outs-and-stop) and the [limits](#limits). Hive sends one
text to one number at a time: a request to schedule a text, send to several numbers at once, or
send anything other than plain text is refused. The approval card shows who the text goes to, who
it comes from, and the text itself.

Hive sends texts only through Infobip's SMS send tool. Every other Infobip tool that would send or
change something (bulk or scheduled sends, WhatsApp, Viber, RCS, two-factor codes, and Infobip's
other servers, even one you add yourself as a custom server) is refused until Hive supports it.
Ask can still use a tool the server marks read-only and whose name plainly reads, as it reads on
any [MCP server](https://docs.get-hive.ai/integrations/mcp-servers.md#using-mcp-tools-in-ask).

Texts you send through Infobip appear in your texts, alongside your Twilio texts.

## ClickSend SMS

Hive sends texts through your firm's own [ClickSend](https://www.clicksend.com) account, which
ClickSend bills. ClickSend is send-only in Hive: replies and ClickSend's delivery reports do not
come back to Hive.

**1. Find your username and API key**

In the ClickSend dashboard, open the **API Credentials** page and copy your username and API
key.

**2. Connect ClickSend**

In **Integrations**, find **ClickSend** under **Messaging** and enter the username and API key.

**3. Text a client**

Ask Hive to text a client, or let an agent or workflow text a client whose number is linked.
Each text goes from your ClickSend account's default sender; Hive never picks another sender.

Every ClickSend text passes the same checks as a Twilio text, on every account level: [who Hive
texts](#who-hive-texts), [opt-outs](#opt-outs-and-stop) and the [limits](#limits). A client who
opted out of texts from any of your firm's providers is not texted through ClickSend either. Hive
sends one plain text to one number at a time; it never schedules texts, sends to a contact list, or
sends marketing. The approval card shows who the text goes to, the text, and that it comes from
your default sender.

ClickSend can refuse a single message even when it accepts the request, for example an invalid
number or no credit left. That text shows as failed in your texts.

## Bird

> [!NOTE]
>
> Bird is not listed in **Integrations** yet. Its tile appears under **Messaging** once Hive has
> confirmed it end to end on a live Bird workspace.

[Bird](https://bird.com) sends texts and WhatsApp messages from your firm's own Bird workspace,
which Bird bills. Hive connects to Bird's MCP server at `https://mcp.bird.com`, the way it connects
an [MCP server](https://docs.get-hive.ai/integrations/mcp-servers.md): you approve Hive on Bird's consent page, and Hive asks
only for permission to send texts and WhatsApp messages, so the connection cannot buy numbers or
change billing.

* **Texts.** One text to one number, as a service message. A text goes from one of your
  workspace's own numbers, which Bird checks belongs to you. A sender name instead of a number is
  used only when you approve it on the card; with no sender, the text is refused.
* **WhatsApp.** Only once your workspace has accepted [WhatsApp's terms](#whatsapp-terms). Free text
  goes only to a client who messaged you on WhatsApp in the last 24 hours, which Hive reads from
  Bird before sending. Outside that window, use an approved **utility** or **authentication**
  template with body values only. Marketing templates are refused.
* **Checks.** Every Bird message passes [who Hive texts](#who-hive-texts),
  [opt-outs](#opt-outs-and-stop) and the [limits](#limits), on every account level.
* **Refused.** Every other Bird tool that sends or changes something (batch sends, media, numbers,
  senders, templates, billing, and Bird's general-purpose `execute` tool) is refused. If Hive
  cannot read what it needs from Bird to check a message, the message is refused.

Bird is send-only in Hive: replies are read in Bird. Messages you send appear in your texts.

## WhatsApp with 360dialog

> [!NOTE]
>
> 360dialog is not listed in **Integrations** yet. Its tile appears under **Messaging** once Hive
> has confirmed it end to end on a live 360dialog account.

[360dialog](https://www.360dialog.com) sends WhatsApp messages from your firm's own 360dialog
number, into a conversation in its inbox. 360dialog, and Meta's WhatsApp charges, bill your firm
directly. Hive connects to 360dialog's MCP server at `https://mcp.360dialog.com/mcp` with
360dialog's consent page, asking only to read your channels, templates and inbox and to send.

* **Terms first.** Nothing is sent until your workspace has accepted
  [WhatsApp's terms](#whatsapp-terms).
* **The 24-hour window.** Free text goes only to a client who messaged you in the last 24 hours,
  which Hive reads from the conversation before sending. If Hive cannot read the conversation, it
  treats the window as closed. Outside the window, use a template approved in your own WhatsApp
  account: **utility** or **authentication** only, never marketing.
* **Checks.** Every message passes [who Hive texts](#who-hive-texts),
  [opt-outs](#opt-outs-and-stop) and the [limits](#limits), on every account level.
* **Refused.** Media, interactive messages, and every other 360dialog tool that changes something
  (templates, webhooks, profile, the sandbox) are refused.

360dialog is send-only in Hive: replies are read in 360dialog. Disconnecting Bird or 360dialog
clears the message text Hive kept for it; opt-outs and linked numbers stay.

## Textmagic SMS

> [!NOTE]
>
> Textmagic is not listed in **Integrations** yet. Its tile appears under **Messaging** once Hive
> has confirmed it end to end on a live Textmagic account.

[Textmagic](https://www.textmagic.com/mcp-connector/) is a UK texting service with its own
connector for AI tools. Hive connects to it at `https://mcp.textmagic.com`, the way it connects an
[MCP server](https://docs.get-hive.ai/integrations/mcp-servers.md): you approve Hive on Textmagic's consent page, and Hive
never sees your Textmagic password. Texts go out from your Textmagic account's default sender, and
Textmagic bills your firm for each one.

* **Send.** Hive sends one text to one number with Textmagic's send tool, the number written with
  its country code (`447700900123`), through the same checks as every text, on every account
  level: [who Hive texts](#who-hive-texts), [opt-outs](#opt-outs-and-stop) and the
  [limits](#limits).
* **Receive.** Textmagic does not post replies to Hive, so about once an hour Hive reads your
  account's new replies and adds them to your texts in **Settings → Account → Texting clients**.
  Replies from before you connected are not imported, except a STOP or START among your latest
  replies, which still applies. A reply from a number you have not linked raises the same Inbox card as a text, and a
  client who sends **STOP** is opted out for the whole workspace. Replies from linked clients reach
  Signals; they do not start workflows yet.
* **Refused.** Every other Textmagic tool that sends or changes something, such as bulk or
  scheduled sends, campaigns and contact lists, is refused, whatever your account level. Ask can
  still use a tool Textmagic marks read-only and whose name plainly reads, as it reads on any
  [MCP server](https://docs.get-hive.ai/integrations/mcp-servers.md#using-mcp-tools-in-ask).

Textmagic does not report delivery back to Hive, so a text it accepted shows as sent.

## WhatsApp Business

Every workspace can connect **WhatsApp Business** on the **Integrations** page, once it has
accepted [WhatsApp's terms](#whatsapp-terms). It uses your firm's own WhatsApp Business account on
Meta's WhatsApp Cloud API, and Meta bills your firm for each conversation; Hive adds no messaging
charge. Hive sends service messages only, such as reminders, document requests and replies, never
marketing.

> [!TIP]
>
> New to Meta's WhatsApp Cloud API? The [WhatsApp set-up guide](https://docs.get-hive.ai/integrations/whatsapp-setup.md) walks
> through the Meta app, the phone number, a permanent token, the IDs, the app secret and the
> webhook, and through registering a Twilio WhatsApp sender.

### WhatsApp terms

Before anyone in your workspace connects WhatsApp, sets up a WhatsApp number or sends a WhatsApp
message, a member who can connect WhatsApp accepts these terms for the firm. Hive shows them when
you select **Connect** on the WhatsApp Business tile, and under **WhatsApp terms** in **Settings →
Account → Texting clients**:

* Your business sends from its own WhatsApp Business account, under Meta's WhatsApp Business
  terms and policies.
* Use it for service messages to clients who have agreed to hear from you, and no marketing
  without opt-in.
* Meta may restrict your number if its rules are broken, and your firm is responsible for what it
  sends.
* Hive is not offered as a general-purpose AI assistant over WhatsApp.

They point to Meta's
[WhatsApp Business Messaging Policy](https://business.whatsapp.com/policy) and
[WhatsApp Business Solution Terms](https://www.whatsapp.com/legal/business-solution-terms). Tick
**I accept these terms for my firm**, then select **Accept and connect** (or **Accept terms** in
Settings). Hive records who accepted, when, and which version of the terms, for the whole
workspace.

Workspace admins can always accept. Other members can accept once an admin has enabled WhatsApp
Business for members; otherwise Hive asks them to ask an admin. Until the terms are accepted, Hive
refuses to connect WhatsApp Business, to save a WhatsApp number's set-up, and to send any WhatsApp
message, through Meta or Twilio, and Ask and Agent Studio offer no WhatsApp action. When Hive
changes the terms, everyone is asked to accept the new version before Hive sends more WhatsApp
messages.

### Connect WhatsApp Business

| | |
| - | - |
| **Connect** | API key: a Meta access token (a system user token) with WhatsApp messaging and management access, from your Meta app. |
| **Receive** | Messages to the one WhatsApp number you set up, and delivery and read reports for messages Hive sent. |
| **Actions** | **Send a message** (within 24 hours of the client's last message), **Reply to a message**, and **Send a template message** (any time). |

**1. Connect WhatsApp Business**

In **Integrations**, select **Connect** on **WhatsApp Business**, accept
[WhatsApp's terms](#whatsapp-terms) if Hive asks, and enter your Meta access token.

**2. Save the set-up**

Open **Settings → Account → Texting clients**. Under your WhatsApp connection, enter the
**Phone number ID** and the **WhatsApp Business account ID** (both under WhatsApp → API Setup
in your Meta app) and the **Meta app secret** (App settings → Basic), then select **Save
set-up**. Hive checks the number belongs to that account, keeps the app secret encrypted and
never shows it again.

**3. Point Meta's webhook at Hive**

Hive then shows a **Callback URL** and a **Verify token**. In your Meta app, open WhatsApp →
Configuration, edit the webhook, paste both, and subscribe to the `messages` field. Copy the
verify token straight away: Hive shows it once, and saving the set-up again makes a new one.

**4. Check it is live**

Once Meta has checked the callback URL, the page reads **Receiving WhatsApp messages on** your
number and lists your templates. Until then Hive neither receives nor sends WhatsApp messages.

Hive accepts a WhatsApp post only when Meta signed it with your app secret, and only for the
number you set up: if your Meta app serves other numbers too, their messages are dropped unread.

**The 24-hour window.** WhatsApp lets a business send a free-form message only within 24 hours of
the client's last message to that number. Outside that window Hive refuses the message and asks
you to use a template instead, on every account level. **Send a template message** works any time
with an approved template from your WhatsApp Business account. Hive reads your templates from
WhatsApp when it sends, so a template paused or changed in WhatsApp Manager is refused at once.
Hive refuses **marketing** templates, and templates that are not approved yet; the template list in
Texting clients marks a marketing template as one Hive will not send.

Everything else on this page applies to WhatsApp as to texts: who Hive messages, opt-outs (a
client who sends **STOP** on WhatsApp is opted out of WhatsApp messages, separately from texts),
who sees messages, the hourly and daily limits, and Inbox cards. Messages from WhatsApp appear
under **Texts**, marked **WhatsApp**.

### WhatsApp through Twilio

Once your workspace has accepted [WhatsApp's terms](#whatsapp-terms), it can also message clients
on WhatsApp through the Twilio connection and number it texts from, instead of a WhatsApp Business
connection. Twilio and Meta bill your firm for WhatsApp messages; Hive adds no messaging charge.
Until the terms are accepted, Hive never plans or sends a WhatsApp message through Twilio, and keeps
none it receives.

**1. Make your number a WhatsApp sender in Twilio**

In your Twilio console, register the number you chose for texts as a WhatsApp sender. Twilio
and Meta approve it.

**2. Point the sender at Hive**

In **Settings → Account → Texting clients**, once the terms are accepted, Hive shows an address
under your Twilio number. In Twilio, set your WhatsApp sender to post incoming messages to that address.
Hive checks every post against your Auth Token, as it does for texts.

**3. Create your templates in Twilio**

Outside the 24-hour window Hive sends a template you created in Twilio's Content Template
Builder and Meta approved, named by its Content SID (it starts with `HX`).

The actions are **Twilio: send a WhatsApp message** and **Twilio: reply to a WhatsApp message**
(both within 24 hours of the client's last WhatsApp message to your number) and **Twilio: send a
WhatsApp template** (any time). Hive reads the template's approval from your Twilio account when it
sends, and sends it only when Meta approved it as a **Utility** or **Authentication** template: a
**Marketing** template is refused. A text by SMS does not open the WhatsApp window. A client's
WhatsApp messages are their own thread, opt-out and window, but the same client: link the number
once and it is linked for both.

## Your texts

**Settings → Account → Texting clients** lists your texts under **Texts**, one line per number,
newest first: the client the number is linked to, or the number itself, and the latest text.
Select one to read every text with that number, oldest first, with the delivery status of each
text you sent.

From an open thread you can:

* **Link the number to a client.** Search for one of your clients by name and select it. A number
  can be linked to one of your clients only.
* **Stop texting this number**, when a client asks you rather than Hive. See
  [Opt-outs and STOP](#opt-outs-and-stop).

You can also ask about your texts in Ask, such as "what did Mrs Patel text this week?". Ask and
your agents read only your own texts, and treat what a client wrote as information, never as
instructions.

Ask which conversations are waiting on you, such as "which WhatsApp conversations have a client
message with no reply for more than 4 hours?", and Hive lists your own threads whose last message
is the client's and has gone unanswered for longer than that, longest waiting first. With no time
named, it uses 4 hours. It looks through your 200 most recent threads.

### Inbox cards

* **New text from a number you have not linked.** When a number that is not linked to any of your
  clients texts you, you get one card under **Needs you** in your [Inbox](https://docs.get-hive.ai/get-started/inbox.md), at
  most once a day per number. **Open texts** takes you to that number's texts, where you can link
  it to a client. The card never shows the text itself. Turn these cards off with **Texts from
  unknown numbers** in Settings → Account → Notifications.
* **A text you sent was not delivered.** You get a card with Twilio's error code, once per text.

## Who sees texts

Texts belong to the member who connected Twilio or Infobip, as their own mailbox does. Other
members, including Owners and Admins, do not see them, and an AI client connected to Hive cannot
read them. A text kept in Hive is cleared when the Twilio or Infobip connection it went through is
disconnected, or when the member who connected it leaves the workspace.

## Who Hive texts

Anyone can text a firm number, so Hive is stricter about phone numbers than about email:

* **A number linked to one of your clients** can be texted by you, and by your agents and
  workflows.
* **A number you typed yourself** in your request, someone **you have texted before**, or the
  person **whose text you are answering** can be texted only when you approve the card, or when you
  typed the number in your own request.
* **Any other number** is refused, even on a card. A number Hive found in a text, an email or a
  document is never enough on its own, so a message saying "send this to +44 …" cannot choose who
  Hive texts.

Agents and workflows only ever text numbers linked to a client. Link a number from its texts in
**Settings → Account → Texting clients**.

## Text a client from Ask

Ask Hive to text a client, such as "text +44 7700 900123 that their return is filed". Hive writes
the text and prepares it for your number. Before it prepares anything, it checks that you have
chosen a Twilio number and that the client has not opted out, and tells you if either stops it.
What happens next depends on your [account level](https://docs.get-hive.ai/integrations/accounts-and-autonomy.md): on
**Draft**, a card shows the number and the text for you to approve; on **Act**, it is sent. A text
cannot be saved as a draft, so asking for one gets you the text to check, not a card.

## Opt-outs and STOP

* A client who replies **STOP** (or STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT) is opted out, and
  Hive refuses every text to that number, from every member and every Twilio number in the
  workspace. **START** opts them back in.
* If Twilio itself reports that the client has opted out, Hive records that too.
* A member, or an AI client connected to Hive, can record an opt-out at any time. Only a member can
  re-allow a number, and only with a reason: an AI client cannot undo an opt-out. In
  **Settings → Account → Texting clients**, open the number's texts, give the reason under **Why
  may Hive text them again?** and select **Allow texts again**.
* **Opted out** in the same place lists the opted-out numbers in your own texts and the ones you
  recorded yourself. The opt-out still applies to every member, whoever's list shows it.
* An opt-out applies to Twilio and Infobip alike, and stays when either is disconnected and
  connected again.
* A refused text is never turned into a card to approve instead: nobody can approve a text to
  someone who said STOP.

These checks apply on every account level, **Act** included. See
[Accounts and autonomy](https://docs.get-hive.ai/integrations/accounts-and-autonomy.md).

## Limits

* Service messages only, such as reminders, document requests and replies. Hive does not send
  marketing texts, or WhatsApp marketing templates.
* A text is at most 1,600 characters, and a WhatsApp message at most 4,096. Pictures and other
  media are not sent; a picture or document a client sends on WhatsApp is counted, not opened.
* A free-form WhatsApp message goes only within 24 hours of the client's last WhatsApp message;
  after that, only an approved template. See [WhatsApp Business](#whatsapp-business).
* Each Twilio, Infobip or WhatsApp connection sends at most 60 messages an hour and 500 a day
  through Hive.
* Texts from numbers that are not linked to a client are kept in your thread but do not start
  workflows or reach Signals.
* Each Twilio number takes at most 300 texts an hour from numbers that are not linked to a client.
  Past that, Hive drops them unread, so a flood of texts cannot bury your clients'. Texts from
  your clients, and STOP and START, are always received; past the limit, a START from an unlinked
  number gives you no Inbox card. A Telegram bot has the same limit.
* A member without a seat receives no texts until they hold one again. A STOP or START sent to
  their number is still recorded.

## Texts in workflows

A **Connected app event** trigger on **Twilio** can start a workflow on these events, from numbers
linked to your clients:

| Event | Type |
| - | - |
| **Text received from a client** | `message.received` |
| **Text not delivered** | `message.failed` |
| **Client opted out of texts** | `contact.opted_out` |

A **Connected app event** trigger on **WhatsApp Business** has the same three events for
WhatsApp messages: **WhatsApp message received from a client**, **WhatsApp message not delivered**
and **Client opted out of WhatsApp messages**. To answer one, use **WhatsApp: reply to a message**
the same way; a reply after the 24-hour window is refused, so use **WhatsApp: send a template
message** instead.

A step can read the text with `{{trigger.event.text}}` and the sender with
`{{trigger.event.from}}`. To answer, use the **Twilio: reply to a text** action with
`{{trigger.event.messageId}}` and the sender's number, `{{trigger.event.from}}`: the reply goes to
whoever sent that text, and the card shows that number. A reply whose number is not the sender's
is refused. The **Twilio** trigger also fires for WhatsApp messages through Twilio once the
workspace has accepted WhatsApp's terms; `{{trigger.event.channel}}` is `whatsapp` for those, and **Twilio: reply to a WhatsApp
message** answers them. See
[Connected app event](https://docs.get-hive.ai/workflows/workflow-steps.md#connected-app-event).

## Telegram bot

Hive can receive and send messages through your firm's own Telegram bot, with the Telegram Bot
API. Hive never signs in to a personal Telegram account. A client reaches the firm by opening a
chat with the bot and pressing **Start**; Telegram lets a bot message only people who have written
to it first.

| | |
| - | - |
| **Connect** | API key: your bot's token from BotFather. Each member connects their own bot. |
| **Receive** | Private messages to the bot, and a client blocking the bot. Group chats are ignored. |
| **Actions** | **Send a message** to a client, and **Reply to a message** you received. Service messages only. |
| **Signals** | — |

**1. Create a bot**

In Telegram, open **@BotFather**, send `/newbot` and follow the steps. BotFather gives you the
bot's token. Send `/setjoingroups` and choose **Disable**, so nobody can add the bot to a group.

**2. Connect Telegram**

In **Integrations**, connect **Telegram** under **Messaging** and paste the bot's token.

**3. Receive the bot's messages in Hive**

Open **Settings → Account → Texting clients**. Under **Your numbers and bots**, select
**Receive this bot's messages in Hive**. If the bot already sends its messages somewhere else,
such as another program, Hive shows you that address and changes nothing until you select
**Replace it**. That address then stops receiving the bot's messages.

**4. Share the bot and link your clients**

Hive shows the bot's link, such as `t.me/your_bot`. Share it with your clients. When a client
writes to the bot, open their chat under **Texts** and link it to one of your clients.

Telegram sends each message with a secret Hive chose when it connected the bot, and Hive refuses
any message without it, so nothing else can post messages into your workspace.

How a Telegram bot differs from texts:

* **Who Hive messages.** Only a private chat that has written to this bot. A chat linked to one of
  your clients can be messaged by you, your agents and your workflows; a chat you are answering, or
  one you have messaged before, only when you approve the card. A message to a chat that never
  wrote to the bot is refused, even on a card.
* **Opting out.** A client who blocks the bot, or sends `/stop` or **STOP**, is opted out, and Hive
  refuses every message to that chat, from every member and bot in the workspace. Sending `/start`
  again opts them back in. A member can record or lift an opt-out in **Settings → Account → Texting
  clients**, as for a number.
* **Groups.** Hive ignores group chats, supergroups and channels, even if the bot was added to
  one. A group is never a client.
* **Limits.** A message is plain text of at most 4,096 characters. Pictures and files are not sent
  or kept. Each bot sends at most 60 messages an hour and 500 a day through Hive.
* **Delivery.** Telegram does not report delivery, so a sent message shows as sent.
* **Link previews.** Messages Hive sends through the bot show no link previews: Telegram shows
  links as text and does not fetch them.
* **No sends while reading.** Telegram accepts a send through the same kind of request as a read,
  so Ask never sends Telegram requests while it reads to answer a question: any Telegram request the
  model writes then is refused before it is sent. Messages go out only as the sends described
  above.
* **Inbox cards.** A message from a chat you have not linked gives you a **New Telegram message**
  card under **Needs you**, at most once a day per chat.

A **Connected app event** trigger on **Telegram** can start a workflow on these events, from chats
linked to your clients:

| Event | Type |
| - | - |
| **Telegram message received from a client** | `message.received` |
| **Client blocked the Telegram bot** | `contact.opted_out` |

To answer, use the **Telegram: reply to a message** action with `{{trigger.event.messageId}}` and
the chat, `{{trigger.event.from}}`.

> [!NOTE]
>
> Telegram gives each bot one place to send its messages. A bot connected here cannot also be the
> bot you talk to Hive through. Use a separate bot for each.

When you disconnect Telegram, Hive stops the bot sending its messages to Hive, if it still does,
and clears the messages it kept. Hive does not restore an address the bot used before. Opt-outs
and the chats you linked to clients stay.

## Disconnecting

When you disconnect Infobip SMS, Hive clears the texts it kept from that connection. Opt-outs and
the numbers you linked to clients stay. Disconnecting Textmagic also stops Hive reading its replies,
and clears the texts it kept the same way.

When you disconnect Twilio, Hive points your number back at the address it had before, if it still
points at Hive, stops receiving texts and clears the texts it kept. Opt-outs and the numbers you
linked to clients stay.

When you disconnect WhatsApp Business, Hive stops receiving WhatsApp messages, clears the ones it
kept and deletes the app secret and verify token. Remove Hive's callback URL from your Meta app's
webhook settings too: Hive cannot change them for you.

If you change to a different Twilio number, Hive gives the old number back the address it had
before, then points the new one at Hive. When a member is removed from the workspace, Hive does the
same for their number and clears the texts it kept.

## WhatsApp with Wati

WhatsApp through your firm's own [Wati](https://www.wati.io) account is in a closed pilot, and is
not on the **Integrations** page yet: Wati's sign-in accepts only the AI apps Wati has approved,
and does not accept Hive yet. Your firm pays Wati, and Meta's WhatsApp charges, directly; Hive adds no messaging charge.

In a pilot workspace, once a member has connected Wati's MCP server (`https://mcp.wati.io/mcp`,
`https://eu-mcp.wati.io/mcp` for an EU-hosted Wati account, or `https://ksa-mcp.wati.io/mcp` for
one hosted in Saudi Arabia):

* **Send.** Hive sends one WhatsApp message, or one approved template, to one phone number. The
  same checks as a text apply on every account level: opt-outs, [who Hive texts](#who-hive-texts)
  and the hourly and daily limits. Free text goes only to a client who messaged you on WhatsApp in
  the last 24 hours, which Hive checks with Wati before sending. Outside that window, use an
  approved template. Hive sends **utility** and **authentication** templates only, never marketing
  ones.
* **Receive.** About once an hour, Hive reads the WhatsApp conversations that changed in your Wati
  inbox (up to 100 each time) and adds new messages to your texts in **Settings → Account →
  Texting clients**. A message
  from a number you have not linked raises the same Inbox card as a text. A client who sends
  **STOP** is opted out of WhatsApp for the whole workspace. Messages from linked clients reach
  Signals; they do not start workflows yet.
* **Refused.** Every other Wati tool that sends or changes something, such as bulk template sends,
  media, interactive messages, campaigns and webhook changes, is refused, whatever your account
  level. Messages to Instagram, Messenger or TikTok are refused too.

Outside the pilot, every Wati message is refused and Hive reads nothing from Wati's inbox.
Disconnecting Wati stops the inbox reads and clears the messages Hive kept. Opt-outs and linked
numbers stay.

## Related

> [card] [Connect an app](https://docs.get-hive.ai/integrations/connect-an-app.md)
>
> Connect Twilio, Infobip, ClickSend, Telegram and your other tools.

> [card] [Accounts and autonomy](https://docs.get-hive.ai/integrations/accounts-and-autonomy.md)
>
> How Read, Draft and Act decide what Hive does on its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.