Skip to main content
POST

​
Description

Creates a WhatsApp client in one of your company’s production channels, without starting a conversation. The client shows up in Clients.
  • It only creates WhatsApp clients.
  • The client has no conversation: no message is sent.
  • If the phone is already a client of that channel, it is not changed: the response is a 409 with the existing client.
  • The tags you send are added to the client’s conversation in that channel.

​
Endpoint

​
Before you start

1

Create an API key with the Create clients permission

In Settings → API Keys, create a key and select Clients → Create clients (clients:write). See API Keys.
2

Get the botId of the WhatsApp channel

The botId is the channel’s referenceId. You can see it with the Jelou CLI:
The channel must be in production, not a sandbox, and have a project.
The botId is not the channel’s phone number. If you send the number, the response is a 404 (CLIENT_BOT_NOT_ELIGIBLE).
3

Get the tag IDs (optional)

To add tags, look up their IDs in Tag management. That endpoint uses Basic authentication (clientId:clientSecret), not the API key.

​
Body parameters

​
string
required
Client’s name, 1 to 191 characters. Leading and trailing spaces are removed.
​
string
required
ID of the WhatsApp channel where the client is created (its referenceId). It is not the channel’s phone number.
​
string
required
Mobile number with country code, for example +593991234567. Spaces, dashes, dots and parentheses are allowed; letters are not.
​
integer[]
Numeric IDs of your company’s tags, up to 50 (for example [12, 13]). Tag names are not accepted. They must exist and be active.

​
Authentication

Send the x-api-key header with an API key that has the Create clients permission (clients:write).
​
string
required
Your company’s API key with the clients:write permission.
The clients API is being enabled company by company. If your company does not have it yet, the response is a 403 with the CLIENTS_API_NOT_ENABLED error.

​
Rate limit

Up to 60 requests per minute per company. Past that, the response is a 429 and the Retry-After header tells you how many seconds to wait.

​
Responses

In errors, error.key identifies the case and error.clientMessages has a message to show in Spanish, English and Portuguese. The examples panel has the full response for each case.
In the 409 response for an existing client, tags is empty: tags are neither read nor changed.In tags, name holds the tag’s name per language as it is set up: only the languages it has, and some may be empty.