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

# Criar cliente

> Crie um cliente de WhatsApp em um canal da sua empresa sem iniciar uma conversa

```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 Criado 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 Chave inválida theme={null}
{
  "status": "failed",
  "message": "Unauthorized"
}
```

```json 403 Sem permissão 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 não habilitada 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 Canal inválido 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 Já existe 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 Em criação 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 Corpo inválido 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 Celular inválido 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 Etiquetas inválidas 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 Limite excedido 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 Erro interno 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."
    }
  }
}
```

## Descrição

Cria um cliente de WhatsApp em um canal de produção da sua empresa, sem iniciar uma conversa. O cliente aparece em **Clientes**.

* Só cria clientes de **WhatsApp**.
* O cliente fica **sem conversa**: nenhuma mensagem é enviada.
* Se o celular já é cliente desse canal, **não é alterado**: a resposta é `409` com o cliente existente.
* As etiquetas enviadas são adicionadas à conversa do cliente nesse canal.

## Endpoint

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

## Antes de começar

**1. Crie uma API key com a permissão Criar clientes**

Em **Configurações → API Keys**, crie uma chave e marque **Clientes → Criar clientes** (`clients:write`). Consulte [API Keys](https://docs.jelou.ai/pt/guias/configuracao/chaves-api.md).

**2. Obtenha o botId do canal de WhatsApp**

O `botId` é o `referenceId` do canal. Você pode vê-lo com o [CLI da Jelou](https://docs.jelou.ai/pt/guias/cli/whatsapp.md):

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

O canal deve estar em produção, não em sandbox, e ter um projeto.

> [!WARNING]
>
> O `botId` não é o número de telefone do canal. Se você enviar o número, a resposta é `404` (`CLIENT_BOT_NOT_ELIGIBLE`).

**3. Obtenha os IDs das etiquetas (opcional)**

Para adicionar etiquetas, consulte os IDs em [Gestão de etiquetas](https://docs.jelou.ai/pt/api/etiquetas/gestao-de-etiquetas.md). Esse endpoint usa **autenticação Basic** (`clientId:clientSecret`), não a API key.

## Parâmetros do corpo

**names** `string` *required*

Nome do cliente, de 1 a 191 caracteres. Os espaços no início e no fim são removidos.

**botId** `string` *required*

Identificador do canal de WhatsApp onde o cliente é criado (o seu `referenceId`). Não é o número de telefone do canal.

**phone** `string` *required*

Celular com código do país, por exemplo `+593991234567`. Aceita espaços, hífens, pontos e parênteses; não aceita letras.

**tags** `integer[]`

IDs numéricos de etiquetas da sua empresa, no máximo 50 (por exemplo `[12, 13]`). Não aceita nomes de etiquetas. Devem existir e estar ativas.

## Autenticação

Envie o cabeçalho `x-api-key` com uma API key que tenha a permissão **Criar clientes** (`clients:write`).

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

API key da sua empresa com a permissão `clients:write`.

> [!NOTE]
>
> A API de clientes está sendo habilitada por empresa. Se a sua empresa ainda não a tem, a resposta é `403` com o erro `CLIENTS_API_NOT_ENABLED`.

## Limite de uso

Até **60 requisições por minuto** por empresa. Ao ultrapassar, a resposta é `429` e o cabeçalho `Retry-After` indica quantos segundos esperar.

## Respostas

| Código | Status | Descrição |
| - | - | - |
| 201 | Created | Cliente criado. `data.client` traz o cliente. |
| 401 | Unauthorized | API key inválida ou ausente. Quem responde é o gateway, em outro formato: só `status` e `message`, sem `error`. |
| 403 | Forbidden | A chave não tem a permissão `clients:write` (`API_KEY_SCOPE_MISSING`, E1410; `data.missingScopes` indica quais faltam), ou a API de clientes não está habilitada para a sua empresa (`CLIENTS_API_NOT_ENABLED`, E1411). |
| 404 | Not Found | O `botId` não é um canal de WhatsApp da sua empresa em produção com um projeto (`CLIENT_BOT_NOT_ELIGIBLE`, E1383). |
| 409 | Conflict | O celular já é cliente desse canal (`CLIENT_ALREADY_EXISTS`, E1382; `data.client` traz o cliente existente), ou outra requisição está criando o mesmo cliente (`CLIENT_CREATION_IN_PROGRESS`, E1386; tente de novo em alguns segundos). |
| 422 | Unprocessable Entity | O corpo não é válido (E0422, com o detalhe por campo em `validationError`), o celular não é válido (`CLIENT_INVALID_PHONE`, E1384) ou alguma etiqueta não existe ou está inativa (`CLIENT_TAGS_NOT_FOUND`, E1385). |
| 429 | Too Many Requests | Mais de 60 requisições por minuto (`TOO_MANY_REQUESTS`, E1110). |
| 500 | Internal Server Error | Erro interno do servidor. |

Nos erros, `error.key` identifica o caso e `error.clientMessages` traz uma mensagem para exibir em espanhol, inglês e português. No painel de exemplos está a resposta completa de cada caso.

> [!NOTE]
>
> Na resposta `409` de um cliente existente, `tags` vem vazio: as etiquetas não são consultadas nem alteradas.
>
> Em `tags`, `name` traz o nome por idioma como está configurado na etiqueta: só os idiomas que ela tem, e algum pode vir vazio.


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