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

# Addresses and channels

> How API v2 names where a message leaves from: one entry per address and transport, how from is resolved, and how to connect, switch and remove channels.

## One entry per address and transport

v2 has no sender object. `GET /v2/channels` lists every place the project can
send from, one entry per (address, type):

| Field | Meaning |
| - | - |
| `address` | What the recipient sees: an E.164 number, an email address, `@botname`, `@username`, a Facebook Page id, or `sms_oneway`. |
| `type` | The transport: `sms`, `sms_oneway`, `whatsapp`, `email`, `telegram`, `instagram`, `messenger`, `voice`. |
| `active` | Whether it can send right now. |
| `v1SenderId` | Read-only. The v1 sender behind the entry, for code that still calls v1. |

A number that carries WhatsApp and SMS is two entries with the same address.
`GET /v2/channels/{address}` returns the entries of one address. URL-encode the
address: `+` is `%2B`. Numbers match in any common formatting.

Entries with the same `v1SenderId` belong together: they are one channel group,
the same thing v1 calls a sender. You rarely need to think about groups. They
matter in two places: an agent connected to an address answers on every
transport of its group, and two groups can share an address.

## How `from` is resolved

On `POST /v2/messages` the sending address comes from, in order:

1. `conversationId`: the address the thread was last handled from.
2. `from`: one of your addresses, in any common formatting.
3. The project default, the same one v1 uses without a `Zavu-Sender` header.

`from` is resolved inside your project only. An address no entry has answers
`404 not_found`, with the address in `details.from`.

When two groups share an address, for example a number whose WhatsApp was
connected on one sender and SMS on another, `channel` picks the transport. If
that still does not decide it, the answer is `409 ambiguous_from` with
`details.candidates[{address, type, v1SenderId}]`. Only then does `from` accept
one of those `v1SenderId` values.

## Connect a channel

`POST /v2/channels` connects what needs no purchase and no Meta signup:

| Body | Needs |
| - | - |
| `{"type": "sms_oneway"}` | Nothing. Sends within the SMS daily ceiling; recipients cannot reply. |
| `{"type": "email", "address": "...", "fromName": "..."}` | A verified email domain of the project. |
| `{"type": "telegram", "botToken": "..."}` | A bot token from @BotFather. |

The new channel joins the project's default group when that group does not carry
the transport yet. Otherwise it starts a new group, so a second email address or
a second bot is sent from by naming it in `from`. For one-way SMS and email, an
address that is already connected answers `200` and changes nothing.

Other transports:

* **Two-way SMS and voice** come with a number. `GET /v2/numbers/available`,
  then `POST /v2/numbers` buys the number and turns SMS on in the same call.
  Buying needs a paid plan.
* **WhatsApp, Instagram and Messenger** connect through Meta, from **Accounts**
  in the dashboard. Once connected they appear in `GET /v2/channels`.

## Switch a channel on or off

```bash theme={null}
curl -X POST "https://api.zavu.dev/v2/channels/%2B13125551212/whatsapp/activate" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

`activate` and `deactivate` are the same switch as **Activate** on Accounts in
the dashboard, with the same price. On a paid plan, activating a connection the
plan does not include charges a month at once; the response says how much in
`chargedCents` and `monthlyCents`. `sms`, `sms_oneway` and `voice` have no
switch and are always on.

A connection that would cost money starts inactive. A send without `channel`
skips it; when it was the only way to reach the recipient, the answer is
`409 no_channel` with it in `details.inactive`. A send that names it in
`channel` is refused with `403 channel_inactive`.

## Remove a channel

`DELETE /v2/channels/{address}/{type}` disconnects `sms_oneway`, `telegram` and
`voice`. The others answer `409 disconnect_unavailable` with what to do instead:
switch `whatsapp`, `instagram`, `messenger` or `email` off with `deactivate`, and
manage a number's two-way SMS from **Phone Numbers** in the dashboard.


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