Chat Bridge API

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

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

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

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

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

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

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

Tools

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.

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):

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.

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":"..."}'

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

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

Rate limiting

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

{
  "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:

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

Support

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