> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.chatbridge.mx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.chatbridge.mx/_mcp/server.

# Chat Bridge API

![Chat Bridge](/_fern-files/voices.docs.buildwithfern.com/143b89637fd935fc6366f5f2d967ed9c71d7d0e31f9f92ec006db835a9f0f473/assets/chatbridge-logo.svg)![Chat Bridge](/_fern-files/voices.docs.buildwithfern.com/e9c718da77ce6949ce3288fb09b3f8181033642579f7afab3c70cf36da8751ed/assets/chatbridge-logo-dark.svg)

Chat Bridge is the omnichannel messaging platform by Voices. Its public API lets
you integrate the platform's communication services into your own applications
through an HTTP REST interface. All requests are authenticated with an App-Key
or an OAuth 2.0 access token and use JSON as the data exchange format.

## Available channels

#### [Blaster](/blaster)

Automated phone calls with text-to-speech (TTS) or pre-recorded audio,
outbound routes, audio upload, and webhook notifications.

#### [Email](/email)

Send transactional emails from the templates of your account, query the
sender and templates, and receive delivery, open, and click events through
webhooks.

#### [OMIA](/omia)

Conversational AI phone calls: query the agents and dial types available
for your account, originate calls with agent variables, and receive call
results through webhooks.

#### [RCS](/rcs)

Send rich messages (text, rich cards, carousels) from RCS agents using
templates, and receive delivery statuses, clicks, and replies through
webhooks.

#### [SMS](/sms)

Send transactional and bulk SMS from the masks (senders) enabled for your
account, append trackable short links, and receive delivery statuses
through webhooks.

#### [WhatsApp](/whats-app)

Send text, media, interactive, and template messages; manage templates and
accounts; and receive webhook notifications.

## Tools

#### [Short Links](/tools)

Create trackable short links on `sl2.mx` and query their clicks. Available
to every App-Key regardless of channel.

#### [Authentication](/authentication/api-key)

Authenticate with an API Key or with OAuth 2.0 client credentials. Both
credentials are provided by Voices.

## Getting started

To use the API you need an App-Key, which you can request from the Chat Bridge
team. The App-Key comes preconfigured with the account and channel it is enabled
for, so you don't need to specify them on each request.

> **Info**
>
> A single App-Key enables one channel. If you need to operate both Blaster and
> WhatsApp, request one App-Key per channel. The Tools endpoints (Short Links)
> accept any App-Key.

## Authentication

Every request must carry one of two credentials. Both identify the same
App-Key, so account, channel, webhooks and rate limit are identical whichever
you use.

Both credentials are **provided by Voices**: request them from the Chat Bridge
team.

### Option 1 — API Key

Include the API Key issued by Voices in the `x-api-key` header of every
request (see [API Key](/authentication/api-key)):

```bash
curl https://connect.chatbridge.mx/v1/whatsapp/accounts \
  -H "x-api-key: YOUR_APP_KEY"
```

### Option 2 — OAuth 2.0 client credentials

Exchange the `client_id` and `client_secret` issued by Voices for a
short-lived access token, then send it as a Bearer token. Tokens last 1 hour
(`expires_in`); cache and reuse them instead of requesting one per call.

```bash
curl -X POST https://connect.chatbridge.mx/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"ck_...","client_secret":"..."}'
```

```json
{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3600 }
```

```bash
curl https://connect.chatbridge.mx/v1/whatsapp/accounts \
  -H "Authorization: Bearer eyJhbGciOi..."
```

If a request carries both headers, `Authorization: Bearer` takes precedence.
See [OAuth 2.0](/authentication/oauth/issue-access-token) in the Authentication section for the full contract of the
token endpoint (request formats, errors and per-IP limits).

### Authentication errors

The following scenarios produce an authentication or authorization error. The
`Message` column shows the literal string returned by the API:

| Scenario                                                         | HTTP  | errorCode | Message                                                  |
| ---------------------------------------------------------------- | ----- | --------- | -------------------------------------------------------- |
| No `x-api-key` nor `Authorization` header                        | `401` | 401       | Token de autenticación requerido                         |
| The `x-api-key` does not exist or is incorrect                   | `401` | 401       | App-key inválida                                         |
| The App-Key is disabled                                          | `401` | 401       | App-key inactiva                                         |
| The App-Key only accepts OAuth 2.0 and `x-api-key` was sent      | `401` | 450       | Esta app-key ya no acepta x-api-key, usa OAuth 2.0       |
| The access token is invalid, expired or its App-Key was disabled | `401` | 455       | Token de acceso inválido, expirado o app-key desactivada |
| The App-Key has no access to the requested channel               | `403` | 403       | Esta app-key no tiene acceso a este canal                |

## Rate limiting

If your App-Key has a configured limit, a 60-second window applies. When
exceeded, the API responds with status `429`:

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Has superado el límite de requests permitidos por minuto",
  "errorCode": 300
}
```

## Error format

Every error follows the same structure:

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Descripción del problema",
  "errorCode": 301
}
```

| Field        | Type   | Description                                      |
| ------------ | ------ | ------------------------------------------------ |
| `statusCode` | number | HTTP status code.                                |
| `error`      | string | HTTP error type.                                 |
| `message`    | string | Human-readable description of the problem.       |
| `errorCode`  | number | Internal code, useful when reporting to support. |
| `metadata`   | object | Additional information (optional).               |

## Support

For questions or to report an issue, contact the Chat Bridge team and include
the `errorCode` shown in the error response.