> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create client

> Create a WhatsApp client in one of your company's channels without starting a conversation

```bash cURL theme={null}
curl --request POST \
  --url https://gateway.jelou.ai/platform/v3/companies/clients \
  --header 'x-api-key: API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "names": "Ana Pérez",
    "botId": "BOT_ID",
    "phone": "+593991234567",
    "tags": [12]
  }'
```

```json 201 Created theme={null}
{
  "message": [
    "Client has been created."
  ],
  "statusMessage": "success",
  "status": 1,
  "data": {
    "client": {
      "referenceId": "593991234567",
      "botId": "BOT_ID",
      "names": "Ana Pérez",
      "roomId": "G:BOT_ID:593991234567",
      "createdAt": "2026-11-05T21:00:38.548Z",
      "tags": [
        {
          "id": 12,
          "name": {
            "en": "",
            "es": "VIP"
          },
          "color": "#46bba4"
        }
      ]
    }
  }
}
```

```json 401 Invalid key theme={null}
{
  "status": "failed",
  "message": "Unauthorized"
}
```

```json 403 Missing permission theme={null}
{
  "data": {
    "missingScopes": [
      "clients:write"
    ]
  },
  "message": [
    "Your API key is not allowed to perform this action."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1410",
    "key": "API_KEY_SCOPE_MISSING",
    "description": "The API key used through the gateway does not grant the scope the route requires.",
    "developerMessages": {
      "es": "La API key no incluye el permiso requerido.",
      "en": "The API key does not include the required scope.",
      "pt": "A chave de API não inclui o escopo exigido."
    },
    "clientMessages": {
      "es": "Tu API key no tiene permiso para realizar esta acción.",
      "en": "Your API key is not allowed to perform this action.",
      "pt": "Sua chave de API não tem permissão para realizar esta ação."
    }
  }
}
```

```json 403 API not enabled theme={null}
{
  "message": [
    "The clients API is not available for your account yet."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1411",
    "key": "CLIENTS_API_NOT_ENABLED",
    "description": "The clients API is not enabled for the company yet (apps_clients_v2_phase3 is off).",
    "developerMessages": {
      "es": "La API de clientes no está habilitada para esta compañía.",
      "en": "The clients API is not enabled for this company.",
      "pt": "A API de clientes não está habilitada para esta empresa."
    },
    "clientMessages": {
      "es": "La API de clientes aún no está disponible para tu cuenta.",
      "en": "The clients API is not available for your account yet.",
      "pt": "A API de clientes ainda não está disponível para sua conta."
    }
  }
}
```

```json 404 Invalid channel theme={null}
{
  "message": [
    "Clients cannot be created in this channel. Choose a WhatsApp channel in production."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1383",
    "key": "CLIENT_BOT_NOT_ELIGIBLE",
    "description": "Error thrown when the bot is not a production WhatsApp channel of the company linked to a project.",
    "developerMessages": {
      "es": "El bot no existe en la compañía o no es un canal de WhatsApp en producción con proyecto.",
      "en": "The bot does not belong to the company or is not a production WhatsApp channel with a project.",
      "pt": "O bot não pertence à empresa ou não é um canal de WhatsApp em produção com projeto."
    },
    "clientMessages": {
      "es": "El canal no permite crear clientes. Elige un canal de WhatsApp en producción.",
      "en": "Clients cannot be created in this channel. Choose a WhatsApp channel in production.",
      "pt": "Não é possível criar clientes neste canal. Escolha um canal de WhatsApp em produção."
    }
  }
}
```

```json 409 Already exists theme={null}
{
  "data": {
    "client": {
      "referenceId": "593991234567",
      "botId": "BOT_ID",
      "names": "Ana Pérez",
      "roomId": "G:BOT_ID:593991234567",
      "createdAt": "2026-10-20T10:00:00.000Z",
      "tags": []
    }
  },
  "message": [
    "This client already exists."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1382",
    "key": "CLIENT_ALREADY_EXISTS",
    "description": "Error thrown when the phone is already a client of the bot.",
    "developerMessages": {
      "es": "El celular ya es un cliente de este canal.",
      "en": "The phone is already a client of this channel.",
      "pt": "O celular já é um cliente deste canal."
    },
    "clientMessages": {
      "es": "Este cliente ya existe.",
      "en": "This client already exists.",
      "pt": "Este cliente já existe."
    }
  }
}
```

```json 409 Being created theme={null}
{
  "message": [
    "This client is being created right now. Try again in a few seconds."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1386",
    "key": "CLIENT_CREATION_IN_PROGRESS",
    "description": "Error thrown when the same client is being created by another request.",
    "developerMessages": {
      "es": "Otra solicitud está creando este cliente.",
      "en": "Another request is creating this client.",
      "pt": "Outra solicitação está criando este cliente."
    },
    "clientMessages": {
      "es": "Este cliente se está creando en este momento. Intenta de nuevo en unos segundos.",
      "en": "This client is being created right now. Try again in a few seconds.",
      "pt": "Este cliente está sendo criado agora. Tente novamente em alguns segundos."
    }
  }
}
```

```json 422 Invalid body theme={null}
{
  "message": [
    "Los valores ingresados no son correctos."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0422",
    "key": "VALIDATOR_ERROR",
    "description": "Error to be thrown when cannot process request because of incoming values",
    "developerMessages": {
      "es": "Los valores del request no son correctos para ser procesados.",
      "en": "The request values are not correct for processing.",
      "pt": "Os valores do request não estão corretos para serem processados."
    },
    "clientMessages": {
      "es": "Los valores ingresados no son correctos.",
      "en": "The values entered are not correct.",
      "pt": "Os valores inseridos não estão corretos."
    }
  },
  "validationError": {
    "names": [
      {
        "pt": "O campo names é obrigatório e deve ter no máximo 191 caracteres.",
        "es": "El campo names es obligatorio y debe tener máximo 191 caracteres.",
        "en": "The names field is required and must have at most 191 characters."
      }
    ]
  }
}
```

```json 422 Invalid phone theme={null}
{
  "message": [
    "Enter the mobile number with the country code."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1384",
    "key": "CLIENT_INVALID_PHONE",
    "description": "Error thrown when the client phone is not a valid number with country code.",
    "developerMessages": {
      "es": "El celular no es un número válido con código de país.",
      "en": "The phone is not a valid number with country code.",
      "pt": "O celular não é um número válido com código do país."
    },
    "clientMessages": {
      "es": "Ingresa el celular con el código de país.",
      "en": "Enter the mobile number with the country code.",
      "pt": "Informe o celular com o código do país."
    }
  }
}
```

```json 422 Invalid tags theme={null}
{
  "message": [
    "One or more tags do not exist."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1385",
    "key": "CLIENT_TAGS_NOT_FOUND",
    "description": "Error thrown when a tag does not exist or is inactive in the company.",
    "developerMessages": {
      "es": "Una o más etiquetas no existen o están inactivas en la compañía.",
      "en": "One or more tags do not exist or are inactive in the company.",
      "pt": "Uma ou mais etiquetas não existem ou estão inativas na empresa."
    },
    "clientMessages": {
      "es": "Una o más etiquetas no existen.",
      "en": "One or more tags do not exist.",
      "pt": "Uma ou mais etiquetas não existem."
    }
  }
}
```

```json 429 Rate limit theme={null}
{
  "message": [
    "You have exceeded the request limit. Please try again later."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1110",
    "key": "TOO_MANY_REQUESTS",
    "description": "Rate limit exceeded. Too many requests in a short period.",
    "developerMessages": {
      "es": "Ha excedido el límite de solicitudes. Por favor, intente de nuevo más tarde.",
      "en": "You have exceeded the request limit. Please try again later.",
      "pt": "Você excedeu o limite de solicitações. Por favor, tente novamente mais tarde."
    },
    "clientMessages": {
      "es": "Ha excedido el límite de solicitudes. Por favor, intente de nuevo más tarde.",
      "en": "You have exceeded the request limit. Please try again later.",
      "pt": "Você excedeu o limite de solicitações. Por favor, tente novamente mais tarde."
    }
  }
}
```

```json 500 Internal error theme={null}
{
  "message": [
    "We are having trouble processing your request. Please try again later."
  ],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0000",
    "key": "UNKNOWN_ERROR",
    "description": "Error to be thrown when it couldn't be determined the reason of failure",
    "developerMessages": {
      "es": "Error inesperado occurido, revisar logs.",
      "en": "Unexpected error occurred, check logs."
    },
    "clientMessages": {
      "es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta mas tarde.",
      "en": "We are having trouble processing your request. Please try again later."
    }
  }
}
```

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

```
POST https://gateway.jelou.ai/platform/v3/companies/clients
```

## 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](https://docs.jelou.ai/en/guides/settings/api-keys.md).

**2. Get the botId of the WhatsApp channel**

The `botId` is the channel's `referenceId`. You can see it with the [Jelou CLI](https://docs.jelou.ai/en/guides/cli/whatsapp.md):

```bash theme={null}
jelou channels list --type Whatsapp
```

The channel must be in production, not a sandbox, and have a project.

> [!WARNING]
>
> 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](https://docs.jelou.ai/en/api/tags/tag-management.md). That endpoint uses **Basic authentication** (`clientId:clientSecret`), not the API key.

## Body parameters

**names** `string` *required*

Client's name, 1 to 191 characters. Leading and trailing spaces are removed.

**botId** `string` *required*

ID of the WhatsApp channel where the client is created (its `referenceId`). It is not the channel's phone number.

**phone** `string` *required*

Mobile number with country code, for example `+593991234567`. Spaces, dashes, dots and parentheses are allowed; letters are not.

**tags** `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`).

**x-api-key** `string` *required*

Your company's API key with the `clients:write` permission.

> [!NOTE]
>
> 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

| Code | Status | Description |
| - | - | - |
| 201 | Created | Client created. `data.client` holds the client. |
| 401 | Unauthorized | Invalid or missing API key. The gateway answers it in another format: only `status` and `message`, without `error`. |
| 403 | Forbidden | The key does not have the `clients:write` permission (`API_KEY_SCOPE_MISSING`, E1410; `data.missingScopes` lists the missing ones), or the clients API is not enabled for your company (`CLIENTS_API_NOT_ENABLED`, E1411). |
| 404 | Not Found | The `botId` is not a production WhatsApp channel of your company with a project (`CLIENT_BOT_NOT_ELIGIBLE`, E1383). |
| 409 | Conflict | The phone is already a client of that channel (`CLIENT_ALREADY_EXISTS`, E1382; `data.client` holds the existing client), or another request is creating the same client (`CLIENT_CREATION_IN_PROGRESS`, E1386; try again in a few seconds). |
| 422 | Unprocessable Entity | The body is not valid (E0422, with the details per field in `validationError`), the phone is not valid (`CLIENT_INVALID_PHONE`, E1384), or a tag does not exist or is inactive (`CLIENT_TAGS_NOT_FOUND`, E1385). |
| 429 | Too Many Requests | More than 60 requests per minute (`TOO_MANY_REQUESTS`, E1110). |
| 500 | Internal Server Error | Internal server error. |

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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.