Start a chat | Swarmhit Developers

One attendee: a message to that person (their chat is reused when it exists; a first message counts as a new chat against the caps and WhatsApp's quota, and the number is checked to be on WhatsApp first). Two or more: a new group named subject, with an optional first message. JSON, or multipart for files. Answers 201.

Authorization

X-API-KEY<token>

Your API key from the console (gw_live_…).

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

JSON or multipart/form-data (needed for files). A list repeats its field name in multipart.

account_id?string

The number (wa_…). On POST /chats required; on a chat's messages, required only when the chat is named by JID.

attendees_ids?|array<string>

POST /chats only: one person (a JID or a phone number) for a one-to-one chat, two or more (up to 256) for a new group.

subject?string

POST /chats with two or more attendees: the group's name (required, 100 characters at most).

text?string

The message, up to 65,536 characters. With files, it is the caption of the first image, video or document (sent as its own message before a voice note or audio file). In a group, {{0}}, {{1}}… stand for the mentions. Required unless a file or voice_message is sent.

Lengthlength <= 65536

quote_id?string

Chat messages only: the wam_… message to reply to.

mentions?unknown

People to mention: JSON [{ "profile_id": "<JID>" }] (up to 50; a JID ending in @s.whatsapp.net or @lid), or multipart mentions[0][profile_id]. Write {{0}} in text where the first one goes.

typing_duration?string

Show "typing…" for this many milliseconds before sending (capped at 15,000). Default 0.

unless_replied_since?string

ISO date or epoch ms; if the recipient wrote after it, nothing is sent (409 recipient-replied with replied_at).

client_id?string

Your id for this send. A retry with the same id within 24 h answers the first result instead of sending again.

Lengthlength <= 128

attachments?array<>

Multipart only: the files, up to 10, 20 MB each. Each goes as its own WhatsApp message.

voice_message?file

Multipart only: an audio file sent as a voice note. Any audio format; it is converted to a WhatsApp voice note when needed.

Formatbinary

voice_duration_ms?string

Multipart only: the voice note's length in milliseconds, shown on the note. Optional.

Response Body

`application/json`

curl -X POST "https://example.com/whatsapp/api/v1/chats" \  -H "Content-Type: application/json" \  -d '{    "account_id": "wa_Xk2pQ9rT4vW8yZ1a",    "attendees_ids": [      "33612345678"    ],    "text": "Hello Jane!",    "client_id": "send-2026-10-31-0001"  }'

{  "object": "ChatStarted",  "chat_id": "wac_k3J9sLq2Vx8nB4mR",  "message_id": "wam_P7tR2wQ9zL4kN8vX"}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`