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

# Crear cliente

> Crea un cliente de WhatsApp en un canal de tu compañía sin iniciar una conversación

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

```json 403 Sin permiso 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 no 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 no vá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 Ya 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 En creación 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 Cuerpo 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 Límite superado 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 Error 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."
    }
  }
}
```

## Descripción

Crea un cliente de WhatsApp en un canal de producción de tu compañía, sin iniciar una conversación. El cliente aparece en **Clientes**.

* Solo crea clientes de **WhatsApp**.
* El cliente queda **sin conversación**: no se le envía ningún mensaje.
* Si el celular ya es cliente de ese canal, **no se modifica**: la respuesta es `409` con el cliente existente.
* Las etiquetas que envíes se agregan a la conversación del cliente en ese canal.

## Endpoint

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

## Antes de empezar

**1. Crea una clave API con el permiso Crear clientes**

En **Configuración → Claves API**, crea una clave y marca **Clientes → Crear clientes** (`clients:write`). Consulta [Claves API](https://docs.jelou.ai/guides/configuracion/claves-api.md).

**2. Obtén el botId del canal de WhatsApp**

El `botId` es el `referenceId` del canal. Puedes verlo con el [CLI de Jelou](https://docs.jelou.ai/guides/cli/whatsapp.md):

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

El canal debe estar en producción, no en sandbox, y tener un proyecto.

> [!WARNING]
>
> El `botId` no es el número de teléfono del canal. Si envías el número, la respuesta es `404` (`CLIENT_BOT_NOT_ELIGIBLE`).

**3. Obtén los IDs de las etiquetas (opcional)**

Si quieres agregar etiquetas, consulta sus IDs en [Gestión de etiquetas](https://docs.jelou.ai/api/etiquetas/gestion-de-etiquetas.md). Ese endpoint usa **autenticación Basic** (`clientId:clientSecret`), no la clave API.

## Parámetros del cuerpo

**names** `string` *required*

Nombre del cliente, de 1 a 191 caracteres. Se quitan los espacios al inicio y al final.

**botId** `string` *required*

Identificador del canal de WhatsApp donde se crea el cliente (su `referenceId`). No es el número de teléfono del canal.

**phone** `string` *required*

Celular con código de país, por ejemplo `+593991234567`. Acepta espacios, guiones, puntos y paréntesis; no acepta letras.

**tags** `integer[]`

IDs numéricos de etiquetas de tu compañía, máximo 50 (por ejemplo `[12, 13]`). No acepta nombres de etiquetas. Deben existir y estar activas.

## Autenticación

Envía el encabezado `x-api-key` con una clave API que tenga el permiso **Crear clientes** (`clients:write`).

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

Clave API de tu compañía con el permiso `clients:write`.

> [!NOTE]
>
> La API de clientes se está habilitando por compañía. Si tu compañía todavía no la tiene, la respuesta es `403` con el error `CLIENTS_API_NOT_ENABLED`.

## Límite de uso

Hasta **60 solicitudes por minuto** por compañía. Al superarlo, la respuesta es `429` y el encabezado `Retry-After` indica cuántos segundos esperar.

## Respuestas

| Código | Estado | Descripción |
| - | - | - |
| 201 | Created | Cliente creado. `data.client` trae el cliente. |
| 401 | Unauthorized | Clave API inválida o ausente. La responde el gateway, con otro formato: solo `status` y `message`, sin `error`. |
| 403 | Forbidden | La clave no tiene el permiso `clients:write` (`API_KEY_SCOPE_MISSING`, E1410; `data.missingScopes` indica cuáles faltan), o la API de clientes no está habilitada para tu compañía (`CLIENTS_API_NOT_ENABLED`, E1411). |
| 404 | Not Found | El `botId` no es un canal de WhatsApp de tu compañía en producción con un proyecto (`CLIENT_BOT_NOT_ELIGIBLE`, E1383). |
| 409 | Conflict | El celular ya es cliente de ese canal (`CLIENT_ALREADY_EXISTS`, E1382; `data.client` trae el cliente existente), o otra solicitud está creando el mismo cliente (`CLIENT_CREATION_IN_PROGRESS`, E1386; vuelve a intentar en unos segundos). |
| 422 | Unprocessable Entity | El cuerpo no es válido (E0422, con el detalle por campo en `validationError`), el celular no es válido (`CLIENT_INVALID_PHONE`, E1384) o alguna etiqueta no existe o está inactiva (`CLIENT_TAGS_NOT_FOUND`, E1385). |
| 429 | Too Many Requests | Se superaron las 60 solicitudes por minuto (`TOO_MANY_REQUESTS`, E1110). |
| 500 | Internal Server Error | Error interno del servidor. |

En los errores, `error.key` identifica el caso y `error.clientMessages` trae un mensaje para mostrar en español, inglés y portugués. En el panel de ejemplos tienes la respuesta completa de cada caso.

> [!NOTE]
>
> En la respuesta `409` de un cliente existente, `tags` viene vacío: las etiquetas no se consultan ni se modifican.
>
> En `tags`, `name` trae el nombre por idioma tal como está configurado en la etiqueta: solo los idiomas que tiene, y alguno puede venir vacío.


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