Relay docs
API ReferenceWhatsapp

Create a group

Creates a WhatsApp group with one or more customers and starts a Relay conversation for it. Requires the `conversations:write` scope and a connected WhatsApp number. The hosting number is chosen by `integrationId`, then `from` (the connected number's phone), then — if the workspace has exactly one connected number — that one. WhatsApp will not silently add people who don't have your number saved or who restrict who can add them to groups; those come back in `invited` and must join via `invite_link`. Set `sendInviteLink: true` to have the API DM the link to them. Note: WhatsApp here is powered by an unofficial client, so high-volume group creation carries elevated account-ban risk. Each call creates a new group.

POST
/v1/public/whatsapp/groups

Authorization

bearerAuth
AuthorizationBearer <token>

Workspace API key, e.g. rl_live_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Group subject / name.

participants*array<string>

Customer phone numbers to add (country code + number; +, spaces and dashes are ignored).

Items1 <= items
from?string

Phone number of the connected WhatsApp number that should host the group. Omit if the workspace has a single connected number.

integrationId?string

Exact host number by id (alternative to from).

Formatuuid
shopName?string

Stored on the new conversation's custom attributes as shopName.

customAttributes?

Extra custom attributes merged onto the new conversation.

firstMessage?string

Optional opening message sent to the group and recorded as the first outgoing message.

sendInviteLink?boolean

When true, DM the group invite link to participants WhatsApp wouldn't add directly. Sends an unsolicited 1:1 message, so it is off by default.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/public/whatsapp/groups" \  -H "Content-Type: application/json" \  -d '{    "name": "Order #1234 — Acme",    "participants": [      "919876543210"    ]  }'
{  "group_jid": "[email protected]",  "conversation_id": "cc71b11a-25cd-4c2d-9950-df2cc38e3407",  "invite_link": "https://chat.whatsapp.com/K0wSf7SszqKBDqW9eiCi0s",  "added": [    "string"  ],  "invited": [    "string"  ],  "invites_sent": [    "string"  ],  "not_on_whatsapp": [    "string"  ]}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}

Add members to a group POST

Add one or more customers to an existing WhatsApp group conversation. Requires the `conversations:write` scope and the hosting number to be connected. WhatsApp will not directly add people whose privacy blocks it; those come back in `invited` and must join via `invite_link`. Set `sendInviteLink: true` to have the API DM the link to them.

Promote or demote a group admin POST

Promote a group member to admin (or demote them). Requires the `conversations:write` scope, and the connected number must itself be a group admin (WhatsApp returns 403 otherwise).