# 2Chat API

> 2Chat is a messaging automation platform. The API lets you programmatically send and receive WhatsApp messages, manage contacts, handle webhooks, and more.

Base URL: https://api.p.2chat.io/open
Documentation: https://developers.2chat.co
Authentication: All requests require the `X-User-API-Key` header.

## Getting Started

- Create a 2Chat account: https://app.2chat.io/signup/
- Connect a channel: https://app.2chat.io/channels
- Get an API key: https://app.2chat.io/developers?tab=api-access

## Authentication

- [Authentication](https://developers.2chat.co/docs/API/authentication): How to authenticate API requests using the X-User-API-Key header
- [API Response Codes](https://developers.2chat.co/docs/API/api-response-codes): HTTP status codes and error responses
- [Billing](https://developers.2chat.co/docs/API/billing): API credit usage and billing information

## Agent Skills

AI agents can interact with the 2Chat API using pre-built skills from https://github.com/2ChatCo/agent-skills

Install all skills: `npx skills add 2ChatCo/agent-skills`

| Skill | Install Command |
|---|---|
| 2chat-whatsapp | `npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp` |
| 2chat-whatsapp-groups | `npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp-groups` |
| 2chat-whatsapp-catalog | `npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp-catalog` |
| 2chat-whatsapp-waba | `npx skills add 2ChatCo/agent-skills -s 2chat-whatsapp-waba` |
| 2chat-contacts | `npx skills add 2ChatCo/agent-skills -s 2chat-contacts` |
| 2chat-webhooks | `npx skills add 2ChatCo/agent-skills -s 2chat-webhooks` |
| 2chat-calls | `npx skills add 2ChatCo/agent-skills -s 2chat-calls` |
| 2chat-sms | `npx skills add 2ChatCo/agent-skills -s 2chat-sms` |
| 2chat-users | `npx skills add 2ChatCo/agent-skills -s 2chat-users` |

## Voice SDK

Embeddable, framework-agnostic browser voice calling. Package: `@2chat/voice-sdk` (npm) — also available via the jsDelivr CDN. Outbound + inbound calls, mute, hold, DTMF, transfer. Short-lived JWT auth keeps your long-lived API key off the browser.

- [Overview](https://developers.2chat.co/docs/Voice-SDK/overview): What the SDK does, how auth works, prerequisites
- [Quickstart](https://developers.2chat.co/docs/Voice-SDK/quickstart): Install, mint a JWT, place your first call
- [Authentication](https://developers.2chat.co/docs/Voice-SDK/authentication): POST /open/sdk/access-token — mint short-lived SDK JWTs
- [Device API](https://developers.2chat.co/docs/Voice-SDK/device): `Device` options, methods, events, lifecycle
- [Call API](https://developers.2chat.co/docs/Voice-SDK/call): `Call` accept/reject/mute/hold/DTMF/transfer + quality metrics
- [Errors](https://developers.2chat.co/docs/Voice-SDK/errors): Every `VoiceSDKError` code and how to recover

## MCP Server

The 2Chat MCP server exposes the REST API as Model Context Protocol tools. Connect any MCP-compatible client (Claude, Cursor, ChatGPT, Windsurf, VS Code) over OAuth 2.1.

- [MCP Setup](https://developers.2chat.co/docs/MCP/setup): Server URL, OAuth flow, and per-client connection steps
- [MCP Tools](https://developers.2chat.co/docs/MCP/tools): Catalog of all 36 tools — account, messaging (WhatsApp Web, WABA, SMS), contacts, channels, conversations, groups, statuses, catalogs, and calls

| Parameter | Value |
|---|---|
| Server URL | `https://mcp.2chat.io/mcp` |
| Transport | Streamable HTTP |
| Auth | OAuth 2.1 (Dynamic Client Registration, Authorization Code + PKCE) |

## Users

- [List Account Users](https://developers.2chat.co/docs/API/Users/list-users): GET /open/users — List active users on your 2Chat account (uuid, first_name, last_name, email)

## Contacts

- [Create Contact](https://developers.2chat.co/docs/API/Contacts/create-contact): POST /open/contacts — Create a new contact
- [List Contacts](https://developers.2chat.co/docs/API/Contacts/list-contacts): GET /open/contacts — List all contacts
- [Get Contact](https://developers.2chat.co/docs/API/Contacts/get-contact): GET /open/contacts/{contact-uuid} — Get a specific contact
- [Update Contact](https://developers.2chat.co/docs/API/Contacts/update-contact): PUT /open/contacts/{contact-uuid} — Update a contact
- [Delete Contact](https://developers.2chat.co/docs/API/Contacts/delete-contact): DELETE /open/contacts/{contact-uuid} — Delete a contact
- [Search Contacts](https://developers.2chat.co/docs/API/Contacts/search-contacts): GET /open/contacts/search?query={query} — Search contacts

## Webhooks

- [Supported Types](https://developers.2chat.co/docs/API/Webhooks/supported-types): List of all supported webhook event types
- [Subscribe Manually](https://developers.2chat.co/docs/API/Webhooks/subscribe-manually): POST /open/webhooks/subscribe/{event-name} — Subscribe to a webhook event
- [List All Webhooks](https://developers.2chat.co/docs/API/Webhooks/list-all-webhooks): GET /open/webhooks — List all webhook subscriptions
- [List Webhooks by Channel](https://developers.2chat.co/docs/API/Webhooks/list-webhooks-by-channel): GET /open/webhooks/channel/{channel-uuid} — List webhooks for a specific channel
- [Delete Subscription](https://developers.2chat.co/docs/API/Webhooks/delete-subscription): DELETE /open/webhooks/{webhook-uuid} — Delete a webhook subscription
- [Troubleshooting](https://developers.2chat.co/docs/API/Webhooks/troubleshooting): Common issues and solutions for webhooks

## WhatsApp Web — Numbers & Channel Management

- [List Numbers](https://developers.2chat.co/docs/API/WhatsApp/Web/list-numbers): GET /open/whatsapp/get-numbers — List connected WhatsApp numbers
- [Get Number](https://developers.2chat.co/docs/API/WhatsApp/Web/get-number): GET /open/whatsapp/channel/{channel-uuid} — Get a specific WhatsApp number
- [Create QR Connection](https://developers.2chat.co/docs/API/WhatsApp/Web/channel/create-whatsapp-qr-connection): POST /open/whatsapp/channel/create — Create a WhatsApp connection via QR code
- [Get Channel Status](https://developers.2chat.co/docs/API/WhatsApp/Web/channel/get-channel-status): GET /open/whatsapp/channel/{channel-uuid}/status — Get connection status
- [Execute Channel Command](https://developers.2chat.co/docs/API/WhatsApp/Web/channel/execute-channel-command): POST /open/whatsapp/channel/{channel-uuid}/connect or /open/whatsapp/channel/{channel-uuid}/disconnect — Connect or disconnect a channel
- [Delete Channel](https://developers.2chat.co/docs/API/WhatsApp/Web/channel/delete-channel): DELETE /open/whatsapp/channel/{channel-uuid} — Delete a WhatsApp connection

## WhatsApp Web — Messaging

- [Send Message](https://developers.2chat.co/docs/API/WhatsApp/Web/send-message): POST /open/whatsapp/send-message — Send a WhatsApp message to a contact
- [Send Group Message](https://developers.2chat.co/docs/API/WhatsApp/Web/send-group-message): POST /open/whatsapp/send-group-message — Send a message to a WhatsApp group
- [Get Messages](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/get-messages): GET /open/whatsapp/messages/{from_number} — Get messages by phone number
- [Receive a Message](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/receive-a-message): GET /open/whatsapp/messages/{from_number}/{to_number} — Get conversation messages between two numbers
- [List Conversations](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/list-conversations): GET /open/whatsapp/conversations/{channel-uuid} — List conversations for a channel
- [Get Single Message](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/get-single-message): GET /open/whatsapp/message/{session-key}/{message-uuid} — Get a specific message
- [Delete Message](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/delete-message): DELETE /open/whatsapp/message/{session-key}/{message-uuid} — Delete a message
- [Get Group Messages](https://developers.2chat.co/docs/API/WhatsApp/Web/messages/get-group-messages): GET /open/whatsapp/groups/messages/{group-uuid} — Get messages from a group

## WhatsApp Web — Account

- [Check Number](https://developers.2chat.co/docs/API/WhatsApp/Web/check-number): GET /open/whatsapp/check-number/{your-number}/{number-to-check} — Check if a number is on WhatsApp
- [Set Profile Picture](https://developers.2chat.co/docs/API/WhatsApp/Web/set-profile-picture): POST /open/whatsapp/set-profile-picture/{phone_number} — Set WhatsApp profile picture
- [Set Status](https://developers.2chat.co/docs/API/WhatsApp/Web/Status/set-status): POST /open/whatsapp/set-status/{phone_number} — Set WhatsApp status text (away, only calls, etc.)
- [Set Text Status](https://developers.2chat.co/docs/API/WhatsApp/Web/Status/set-text-status): POST /open/whatsapp/set-text-status/{phone_number} — Set WhatsApp text status with optional styling
- [Set Image Status](https://developers.2chat.co/docs/API/WhatsApp/Web/Status/set-image-status): POST /open/whatsapp/set-image-status/{phone_number} — Set WhatsApp image status
- [Set Video Status](https://developers.2chat.co/docs/API/WhatsApp/Web/Status/set-video-status): POST /open/whatsapp/set-video-status/{phone_number} — Set WhatsApp video status

## WhatsApp Web — Groups

- [Create Group](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/create-group): POST /open/whatsapp/group/create — Create a WhatsApp group
- [List Groups](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/list-whatsapp-groups): GET /open/whatsapp/groups/{phone_number} — List WhatsApp groups
- [List Group Participants](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/list-whatsapp-group-participants): GET /open/whatsapp/group/{group-uuid} — Get group details and participants
- [Add Participant](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/add-participant): POST /open/whatsapp/group/{group-uuid}/add-participant — Add participant(s) to a group
- [Remove Participant](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/remove-participant): POST /open/whatsapp/group/{group-uuid}/remove-participant — Remove participant(s) from a group
- [Promote Participant](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/promote-participant): POST /open/whatsapp/group/{group-uuid}/promote-participant — Promote participant(s) to admin
- [Demote Participant](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/demote-participant): POST /open/whatsapp/group/{group-uuid}/demote-participant — Demote admin to regular participant
- [Set Group Picture](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/set-picture): POST /open/whatsapp/group/{group-uuid}/set-picture — Set group profile picture
- [Set Group Description](https://developers.2chat.co/docs/API/WhatsApp/Web/groups/set-description): POST /open/whatsapp/group/{group-uuid}/set-description — Set group description

## WhatsApp Web — Catalog

- [Add Product](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/add-product): POST /open/whatsapp/catalog/product — Add a product to catalog
- [List Products](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/list-products): GET /open/whatsapp/catalog/products — List products in catalog
- [Edit Product](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/edit-product): PUT /open/whatsapp/catalog/product/{product-id} — Edit a product
- [Delete Product](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/delete-product): DELETE /open/whatsapp/catalog/product/{product-id} — Delete a product
- [Add Product Image](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/add-product-image): POST /open/whatsapp/catalog/product/image/{product-id} — Add images to a product
- [Delete Product Image](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/delete-product-image): DELETE /open/whatsapp/catalog/product/image/{product-id}/{image-index} — Delete a product image
- [Add Collection](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/add-collection): POST /open/whatsapp/catalog/collection — Add a collection
- [List Collections](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/list-collections): GET /open/whatsapp/catalog/collections — List collections
- [Edit Collection](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/edit-collection): PUT /open/whatsapp/catalog/collection/{collection-id} — Edit a collection
- [Delete Collection](https://developers.2chat.co/docs/API/WhatsApp/Web/catalog/delete-collection): DELETE /open/whatsapp/catalog/collection/{collection-id} — Delete a collection

## WhatsApp Web — Webhooks

- [Subscribe](https://developers.2chat.co/docs/API/WhatsApp/Web/webhooks/subscribe): POST /open/webhooks/subscribe/{event-name} — Subscribe to WhatsApp Web webhook events
- [Payload Examples](https://developers.2chat.co/docs/API/WhatsApp/Web/webhooks/payload-examples): Example payloads for WhatsApp Web webhook events

### Supported WhatsApp Web Events

- whatsapp.message.received — Incoming message from a contact
- whatsapp.message.sent — Message sent by you
- whatsapp.message.new — Any new message (sent or received)
- whatsapp.order.received — Order received from a contact
- whatsapp.call.received — Incoming call
- whatsapp.call.made — Outgoing call
- whatsapp.conversation.new — New conversation started
- whatsapp.audio.transcribed — Audio message transcribed
- whatsapp.message.reaction — Reaction to a message
- whatsapp.message.edited — Message edited
- whatsapp.group.message.received — Group message received
- whatsapp.group.message.reaction — Group message reaction
- whatsapp.group.join — Participant joined a group
- whatsapp.group.leave — Participant left a group
- whatsapp.group.remove — Participant removed from a group
- whatsapp.message.receipt.sent — Message delivery receipt (sent)
- whatsapp.message.receipt.received — Message delivery receipt (received)
- whatsapp.message.receipt.read — Message read receipt
- whatsapp.number.status — Number connection status change

## WhatsApp Business API (WABA)

- [Send Message](https://developers.2chat.co/docs/API/WhatsApp/WABA/send-message): POST /open/waba/send-message — Send a WABA message (template with optional IMAGE/VIDEO/DOCUMENT header media, or session text), including template parameter rules: positional arrays, exact counts, 1024-char limit, forbidden characters, OTP templates
- [Get Templates](https://developers.2chat.co/docs/API/WhatsApp/WABA/get-templates): GET /open/waba/templates?phone_number={phone} — Get WABA message templates
- [Get Template by UUID](https://developers.2chat.co/docs/API/WhatsApp/WABA/get-template): GET /open/waba/templates/{template_uuid} — Get a single template with its approval status, the variables required to send it and a ready-to-copy example payload
- [Sync Templates](https://developers.2chat.co/docs/API/WhatsApp/WABA/sync-templates): POST /open/waba/templates/sync?phone_number={phone} — Trigger a background sync of WABA templates from Meta
- [Create Template](https://developers.2chat.co/docs/API/WhatsApp/WABA/create-template): POST /open/waba/templates — Create a WABA message template and submit it to WhatsApp for review (status starts as PENDING)
- [Delete Template](https://developers.2chat.co/docs/API/WhatsApp/WABA/delete-template): DELETE /open/waba/templates/{template_uuid} — Delete a WABA template and all its language variants
- [Conversation Window](https://developers.2chat.co/docs/API/WhatsApp/WABA/conversation-window): GET /open/waba/conversation-window/{from_number}/{to_number} — Check whether the 24-hour customer service window is open for a contact
- [Get Number](https://developers.2chat.co/docs/API/WhatsApp/WABA/get-number): GET /waba/numbers/{waba_uuid} — Get full details of a single WABA number by UUID

### WABA Webhooks

- [Subscribe](https://developers.2chat.co/docs/API/WhatsApp/WABA/webhooks/subscribe): POST /open/webhooks/subscribe/{event-name} — Subscribe to WABA webhook events
- [Payload Examples](https://developers.2chat.co/docs/API/WhatsApp/WABA/webhooks/payload-examples): Example payloads for WABA webhook events

### Supported WABA Events

- whatsapp.waba.message.sent — WABA message sent
- whatsapp.waba.message.received — Incoming WABA message from a contact
- whatsapp.waba.message.receipt.sent — WABA delivery receipt (sent)
- whatsapp.waba.message.receipt.received — WABA delivery receipt (received)
- whatsapp.waba.template.status.updated — WABA template approved, rejected or paused by WhatsApp

## WhatsApp Web — Integrations

### Slack

- [Create Slack Channel](https://developers.2chat.co/docs/API/WhatsApp/Web/integrations/slack/create-slack-channel): Create a Slack channel linked to WhatsApp
- [Link Slack Channel to WhatsApp Group](https://developers.2chat.co/docs/API/WhatsApp/Web/integrations/slack/link-slack-channel-to-whatsapp-group): Link a Slack channel to a WhatsApp group

## SMS

- [Send an SMS Message](https://developers.2chat.co/docs/API/SMS/send-message): POST /open/sms/send — Send an SMS text message to any phone number
- [List SMS Channels](https://developers.2chat.co/docs/API/SMS/list-channels): GET /open/sms/channels — List the SMS channels (numbers) connected to your account
- [Get an SMS Channel](https://developers.2chat.co/docs/API/SMS/get-channel): GET /open/sms/channel/{channel_uuid} — Get the details/status of a single SMS channel
- [List SMS Conversations](https://developers.2chat.co/docs/API/SMS/list-conversations): GET /open/sms/conversations/{channel_uuid} — List distinct contacts on a channel with their latest message
- [Get SMS Messages](https://developers.2chat.co/docs/API/SMS/get-messages): GET /open/sms/messages/{channel_uuid}/{contact_number} — Get the inbound+outbound SMS thread with a contact
- [Get an SMS Message](https://developers.2chat.co/docs/API/SMS/get-message): GET /open/sms/message/{message_uuid} — Get a single SMS message by its UUID

## Numbers (Purchase & Manage)

- [Overview](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/overview): How the Numbers API endpoints work together — search, purchase, and manage phone numbers
- [Get Regions](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/search-regions): GET /open/numbers/regions — Get available regions for a country
- [Get Cities](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/search-cities): GET /open/numbers/cities — Get available cities for a country
- [DID Types](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/did-types): GET /open/numbers/did-types — List available DID number types
- [Get Requirements](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/requirements): GET /open/numbers/requirements — Get regulatory requirements for a country
- [Search Number Groups](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/search-groups): GET /open/numbers/groups — Search available number groups to purchase
- [Available Numbers](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/available-numbers): GET /open/numbers/available — Get specific numbers within a group
- [Reserve a Number](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/reserve-number): POST /open/numbers/reservations — Reserve a number before purchasing
- [List Reservations](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/list-reservations): GET /open/numbers/reservations — List active reservations
- [Cancel Reservation](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/cancel-reservation): DELETE /open/numbers/reservations/{uuid} — Cancel a reservation
- [Purchase Numbers](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/purchase-numbers): POST /open/numbers/purchase — Purchase reserved numbers
- [Delete Virtual Number](https://developers.2chat.co/docs/API/Virtual-Phone-Numbers/delete-virtual-number): DELETE /open/voip/virtual-numbers/{uuid} — Delete a virtual phone number

## Phone Calls

- [List Virtual Numbers](https://developers.2chat.co/docs/API/Phone-Calls/list-virtual-numbers): GET /open/voip/virtual-numbers — List virtual phone numbers
- [List Caller IDs](https://developers.2chat.co/docs/API/Phone-Calls/list-caller-ids): GET /open/voip/caller-ids — List caller IDs
- [Get Call History](https://developers.2chat.co/docs/API/Phone-Calls/get-call-history): GET /open/voip/call-history — Get call detail records with cost info
- [Get Call Details](https://developers.2chat.co/docs/API/Phone-Calls/get-call-details): GET /open/voip/call/{call_uuid} — Get details of a specific call
- [Get Call Price](https://developers.2chat.co/docs/API/Phone-Calls/get-call-price): GET /open/voip/estimated-call-price/{phone-number} — Get the estimated per-minute price for calling a destination

### Phone Call Webhooks

- [Subscribe](https://developers.2chat.co/docs/API/Phone-Calls/webhooks/subscribe): POST /open/webhooks/subscribe/{event-name} — Subscribe to call webhook events
- [Payload Examples](https://developers.2chat.co/docs/API/Phone-Calls/webhooks/payload-examples): Example payloads for call webhook events

### Supported Phone Call Events

- call.status.update — Call status changed
- call.incoming.completed — Incoming call completed
- call.outbound.completed — Outbound call completed