Resumen

Si utilizas la función de múltiples números de WhatsApp de Wati, esta guía explica cómo usar la API de Wati con diferentes números conectados.

Instrucciones

Si tu cuenta de Wati tiene varios números de WhatsApp conectados, puedes usar estos números para enviar y recibir mensajes a través de la API.

Para asegurarte de que una solicitud de API utilice el número de WhatsApp correcto, es posible que debas incluir una clave adicional en la carga útil (payload) o en la URL de la solicitud. La clave requerida y cómo la incluyas dependerán del endpoint de la API que utilices.

Esta guía enumera las API de Wati que actualmente admiten múltiples números de WhatsApp y explica cómo especificar el número de WhatsApp para cada solicitud de API.

Antes de empezar

Autenticación: Crea un token de API con alcance en Connector > API > Create API Token.

Host: https://live-mt-server.wati.io

Las rutas v1 incluyen /{tenantId}/ después del host: https://live-mt-server.wati.io/{tenantId}/api/v1/...
Las rutas v3 NO incluyen /{tenantId}/: https://live-mt-server.wati.io/api/ext/v3/...

Formato de número de teléfono: Usa solo dígitos con el código de país, sin el símbolo "+". Ejemplo: 85264318722.

Nota:

v3 se recomienda para todas las integraciones nuevas. v1 es una versión antigua, pero sigue siendo compatible.

Una respuesta 200 significa que tu solicitud fue aceptada, no que el mensaje se haya entregado. La entrega se confirma mediante los webhooks de Delivered, Read o Replied. Los fallos se informan a través del webhook de Template Message Failed.

Endpoints de la API v1

1. Enviar mensaje de plantilla (Template Message)

Endpoint: POST /{tenantId}/api/v1/sendTemplateMessage

Parámetro	Ubicación	Notas
`channel_number`	Cuerpo (Body)	El número desde el que se envía
`target`	Cuerpo (Body)	Número de teléfono, ContactId o BSUID del destinatario. Cuando se proporciona, `whatsappNumber` es opcional.

2. Enviar mensajes de plantilla (masivo)

Endpoint: POST /{tenantId}/api/v1/sendTemplateMessages

Parámetro	Ubicación	Notas
`channel_number`	Cuerpo (Body)	El número desde el que se envía

3. Enviar mensaje de plantilla mediante CSV

Endpoint: POST /{tenantId}/api/v1/sendTemplateMessageCSV

Parámetro	Ubicación	Notas
`channelNumber`	Consulta (Query)	El número desde el que se envía

4. Actualizar estado del chat

Endpoint: POST /{tenantId}/api/v1/updateChatStatus

Parámetro	Ubicación	Notas
`channelPhoneNumber`	Cuerpo (Body)	El número cuyo estado de chat deseas actualizar

5. Obtener mensajes por número de WhatsApp

Endpoint: GET /{tenantId}/api/v1/getMessages/{whatsappNumber}

Parámetro	Ubicación	Notas
`tenantId`	Ruta (Path)	Tu ID de inquilino (tenant ID) de Wati
`whatsappNumber`	Ruta (Path)	El número de WhatsApp del destinatario
`channelPhoneNumber`	Consulta (Query)	El número conectado desde el que obtener los mensajes

6. Endpoints que aceptan channelPhoneNumber como parámetro de consulta

Los siguientes endpoints utilizan channelPhoneNumber como parámetro de consulta para especificar qué número conectado usar. Para sendSessionMessage, messageText también es un parámetro de consulta.

Endpoint	Método
`/{tenantId}/api/v1/sendSessionMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendSessionFile/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendSessionFileViaUrl/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendInteractiveButtonsMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/sendInteractiveListMessage/{whatsappNumber}`	POST
`/{tenantId}/api/v1/assignOperator/{whatsappNumber}`	POST

Para todos los endpoints anteriores: whatsappNumber (ruta) es opcional cuando se proporciona target.

7. API que funcionan sin especificar un número

Los datos de contacto se comparten en todos los números conectados, por lo que estos endpoints no requieren un número de canal:

API	Endpoint
Añadir contacto	`POST /{tenantId}/api/v1/addContact/{whatsappNumber}`
Actualizar atributos de contacto	`POST /{tenantId}/api/v1/updateContactAttributes/{whatsappNumber}`
Actualizar atributos para múltiples contactos	`POST /{tenantId}/api/v1/updateContactAttributesForMultiContacts` (Solo plan Business)
Obtener lista de contactos	`GET /{tenantId}/api/v1/getContacts`

API v3 — Recomendada para nuevas integraciones

v3 es la versión recomendada para todas las nuevas integraciones. No utiliza /{tenantId}/ en la ruta.

Alcances (scopes) de token — créalos en Connector > API > Create API Token:

contactsv3:* — operaciones de contacto
conversationsv3:* — operaciones de conversación
messagetemplatev3:write — envío de plantillas

Listar números conectados

Endpoint: GET https://live-mt-server.wati.io/api/ext/v3/channels

Devuelve todos los números de WhatsApp conectados a tu cuenta de Wati.

Enviar mensaje de plantilla (v3)

Usa el campo channel en el cuerpo de la solicitud para especificar desde qué número enviar.

El campo target acepta:

Número de teléfono — 85264318722
ContactId
BSUID
Formato con alcance de canal — Channel:85264318722

Compatibilidad de la API con múltiples números de WhatsApp

API	Múltiples números compatibles
Enviar mensaje de plantilla	Sí
Enviar mensajes de plantilla	Sí
Enviar mensaje de plantilla mediante CSV	Sí
Enviar mensaje de sesión	Sí
Enviar archivo de sesión	Sí
Enviar archivo de sesión mediante URL	Sí
Enviar mensaje de botones interactivos	Sí
Enviar mensaje de lista interactiva	Sí
Asignar operador	Sí
Actualizar estado del chat	Sí
Obtener mensajes por número de WhatsApp	Sí
Obtener lista de contactos	Sí
Añadir contacto	Sí
Actualizar atributos de contacto	Sí
Actualizar atributos para múltiples contactos	Sí (Solo plan Business)

Para obtener más información sobre las API de Wati, consulta nuestra documentación oficial para desarrolladores.

Soporte de API de Wati para múltiples números de WhatsApp