get/api/v1/messaging/whatsapp/groupsconversations:readConsultar grupos
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, un `phoneNumberId` fuera del alcance responde 403 `forbidden` con `details.reason: "channel_not_allowed"`.
Parámetros
- phoneNumberIdconsulta · stringobligatorio
Respuesta 200 · { data }
- groupsobject[]obligatorio
- groupIdstringobligatorio
- phoneNumberIdstring | nullobligatorio
- subjectstringobligatorio
- descriptionstring | nullobligatorio
- groupStatus"active" | "suspended" | "deleted"obligatorio
- participantCountintegerobligatorio
- inviteLinkstring | nullobligatorio
- participantsobject[]obligatorio
- waIdstring | nullobligatorio
- userIdstring | nullobligatorio
- leadIdstring | nullobligatorio
- namestring | nullobligatorio
- leadNamestring | nullobligatorio
- deletedobject[]obligatorio
- groupIdstringobligatorio
- phoneNumberIdstring | nullobligatorio
- subjectstringobligatorio
- descriptionstring | nullobligatorio
- groupStatus"active" | "suspended" | "deleted"obligatorio
- participantCountintegerobligatorio
- inviteLinkstring | nullobligatorio
- participantsobject[]obligatorio
- waIdstring | nullobligatorio
- userIdstring | nullobligatorio
- leadIdstring | nullobligatorio
- namestring | nullobligatorio
- leadNamestring | nullobligatorio
- requestsobject[]obligatorio
- requestIdstringobligatorio
- groupIdstring | nullobligatorio
- status"pending" | "created" | "failed"obligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groupswhatsapp_groups:manageCrear un grupo
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, un `phoneNumberId` fuera del alcance responde 403 `forbidden` con `details.reason: "channel_not_allowed"`.
Cuerpo
- phoneNumberIdstringobligatorio
- subjectstringobligatorio
- descriptionstring
- joinApprovalMode"auto_approve" | "approval_required"
Respuesta 202 · { data }
- requestIdstringobligatorio
- groupIdstring | nullobligatorio
- status"pending" | "created" | "failed"obligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
get/api/v1/messaging/whatsapp/groups/{groupId}conversations:readConsultar un grupo
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).
Parámetros
- groupIdruta · stringobligatorio
Respuesta 200 · { data }
- groupIdstringobligatorio
- phoneNumberIdstring | nullobligatorio
- subjectstringobligatorio
- descriptionstring | nullobligatorio
- groupStatus"active" | "suspended" | "deleted"obligatorio
- participantCountintegerobligatorio
- inviteLinkstring | nullobligatorio
- participantsobject[]obligatorio
- waIdstring | nullobligatorio
- userIdstring | nullobligatorio
- leadIdstring | nullobligatorio
- namestring | nullobligatorio
- leadNamestring | nullobligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
patch/api/v1/messaging/whatsapp/groups/{groupId}whatsapp_groups:manageCambiar un grupo
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).
Cuerpo
- subjectstring
- descriptionstring
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
delete/api/v1/messaging/whatsapp/groups/{groupId}whatsapp_groups:manageBorrar un grupo
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groups/{groupId}/invitewhatsapp_groups:manageInvitar contactos al grupo
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).
Cuerpo
- leadIdsstring[]obligatorio
- templateobjectobligatorio
- namestringobligatorio
- languagestring
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/messaging/whatsapp/groups/{groupId}/pinswhatsapp_groups:manageFijar o desfijar un mensaje
Requiere features.whatsappGroups y un número OBA apto. Las mutaciones usan Idempotency-Key; no repitas un unknown_outcome. Los grupos y sus mensajes pertenecen a la cuenta del número original. Con canales limitados, solo los grupos de los números del alcance (los de otro número responden 404).
Cuerpo
- messageIdstringobligatorio
- operation"pin" | "unpin"obligatorio
- expirationDaysinteger
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `feature_disabled`: La función está desactivada en el workspace.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
get/api/v1/messaging/channelsconversations:readNúmeros e integraciones disponibles para mensajería.
WhatsApp y SMS incluyen números; Telegram incluye `bot` (el predeterminado, sin token), `bots` (todos los bots conectados) y numbers vacío. canReceive=null significa que la recepción no está verificada. SMS y Telegram admiten texto con enlaces, sin botones nativos. Con canales limitados, solo los números y bots del alcance.
Respuesta 200 · { data: [ … ], nextCursor }
- channel"whatsapp" | "sms" | "telegram"obligatorio
- configuredbooleanobligatorio
- botobject
Telegram: el bot predeterminado (con canales limitados, el predeterminado del alcance).
- usernamestring | nullobligatorio
- canSendbooleanobligatorio
- canReceiveboolean | nullobligatorio
- botsobject[]
Telegram: todos los bots conectados (los del alcance de la credencial).
- numbersobject[]obligatorio
- phoneNumberIdstringobligatorio
- phoneNumberstring | nullobligatorio
- wabaIdstring | nullobligatorio
- isDefaultbooleanobligatorio
- canSendbooleanobligatorio
- canReceiveboolean | nullobligatorio
- reasonstring | nullobligatorio
- supportedMessageTypesstring[]obligatorio
- balanceCentsnumber | nullobligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/messaging/messagesconversations:writeEnviar por WhatsApp, SMS o una conversación existente de Telegram.
Idempotency-Key obligatoria para evitar duplicados. Sin integración disponible: 403 feature_disabled. WhatsApp requiere plantilla fuera de la ventana. En WhatsApp/SMS el destino debe ser E.164. SMS admite hasta 1600 caracteres y consume saldo. Telegram requiere conversationId del workspace y texto de hasta 4096 caracteres; no admite teléfonos ni inicia chats nuevos, y responde por el bot de esa conversación. Con canales limitados (`key.channelScope`): un número pedido fuera del alcance → 403 `forbidden` con `details.reason: "channel_not_allowed"`; sin pedirlo, el predeterminado del alcance (si no hay ninguno, 403 `feature_disabled` con `details.reason: "channel_not_in_scope"`).
Cuerpo
- channel"whatsapp"obligatorio
- tostring | string
Teléfono E.164 o BSUID. Obligatorio salvo que vaya `userId`.
- userIdstring
BSUID de WhatsApp: país ISO, punto y alfanuméricos (p. ej. `US.13491208655302741918`).
- phoneNumberIdstring
- leadIdstring
- messageobject | object | object | object | objectobligatorio
- type"text"obligatorio
- textstringobligatorio
- previewUrlboolean
Respuesta 201 · { data }
- conversationIdstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- messageIdstring | nullobligatorio
- status"sent" | "queued"obligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 402 `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla. `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
- 409 `invalid_state`: Operación no válida en el estado actual. `conflict`: Conflicto con el estado actual (p. ej. ya existe). `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
- 503 `unavailable`: Servicio no disponible temporalmente.
get/api/v1/messaging/whatsapp/templatesconversations:readPlantillas de la WABA del número seleccionado.
Espejo local de Meta: incluye status, idioma, componentes y botones, el motivo de rechazo y la calidad, y si se creó por API (y por quién). Filtros exactos `name` y `status`. Solo APPROVED es enviable; Meta valida el estado definitivo. No incluye plantillas legacy cuya WABA no se conoce. Con canales limitados (`key.channelScope`), solo de la WABA de un número del alcance: un `phoneNumberId` fuera del alcance → 403 `forbidden` con `details.reason: "channel_not_allowed"`; sin pedirlo, el predeterminado del alcance (si no hay ninguno, 403 `feature_disabled` con `details.reason: "channel_not_in_scope"`).
Respuesta 200 · { data: [ … ], nextCursor }
- idstringobligatorio
- namestringobligatorio
- languagestringobligatorio
- statusstringobligatorio
- categorystring | nullobligatorio
- wabaIdstringobligatorio
- componentsobject[]obligatorio
- rejectedReasonstring | nullobligatorio
- qualityRatingstring | nullobligatorio
- requestedCategorystring | nullobligatorio
- pendingCategoryobject | nullobligatorio
- categorystringobligatorio
- effectiveAtstring | nullobligatorio
- createdVia"api" | "panel" | nullobligatorio
- createdBystring | nullobligatorio
- descriptionstring | nullobligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
put/api/v1/messaging/whatsapp/templates/{name}whatsapp_templates:writeCrear una plantilla de WhatsApp
Crea la plantilla `name` (+ `language`) en la WABA del número indicado (o del predeterminado) y la envía a revisión de Meta: 201 con `status` PENDING. Si ya existe con el mismo contenido, 200 con la actual (repetir es seguro); si existe con OTRO contenido, 409 `conflict` (Be CRM no la edita: editar una aprobada la devuelve a revisión). Si Meta la rechaza al crearla, 400 `invalid_request` con su motivo en `message`. Pasa los `example` a Meta: los exige para cada variable del cuerpo y para la parte variable de una URL. Queda visible en el panel como «Creada por API». Admite cabecera de texto, de ubicación o multimedia (IMAGE, VIDEO, DOCUMENT), variables posicionales o con nombre (`parameterFormat: NAMED`), botones de respuesta rápida, URL, teléfono y copiar código (cupón), ofertas por tiempo limitado, carruseles (CAROUSEL, 2–10 tarjetas) y plantillas de autenticación (botón OTP); las reglas de Meta se comprueban antes de llamarla (400 con el motivo). El archivo de ejemplo de una cabecera multimedia (también la de cada tarjeta) va por enlace https público en `example.header_url`: Be CRM lo descarga (sin redirecciones; tipos y tamaños de Meta) y lo sube a Meta; si no se puede descargar o no vale, 400 `invalid_request` con el motivo. El estado definitivo llega con la aprobación de Meta (consúltalo con `GET /api/v1/messaging/whatsapp/templates?name=`). Con canales limitados, solo en la WABA de un número del alcance (403 `channel_not_allowed` si `phoneNumberId` no lo está); la plantilla es de la WABA entera y la pueden usar sus demás números, también los de otras integraciones.
Cuerpo
- languagestringobligatorio
- category"UTILITY" | "MARKETING" | "AUTHENTICATION"obligatorio
- descriptionstring
- phoneNumberIdstring
- allowCategoryChangeboolean
- parameterFormat"POSITIONAL" | "NAMED"
- messageSendTtlSecondsinteger
- componentsobject | object | object | object | object | object[]obligatorio
- type"HEADER"obligatorio
- format"TEXT" | "LOCATION" | "IMAGE" | "VIDEO" | "DOCUMENT"obligatorio
- textstring
- exampleobject
- header_textstring[]
- header_text_named_paramsobject[]
- param_namestringobligatorio
- examplestringobligatorio
- header_urlstring
Enlace https PÚBLICO del archivo de ejemplo (imagen JPG/PNG ≤ 5 MB, vídeo MP4 ≤ 9 MB, documento PDF ≤ 9 MB). Be CRM lo descarga (sin redirecciones, 15 s como mucho) y lo sube a Meta; se propone como cabecera al enviar.
Respuesta 200 · { data }
- idstringobligatorio
- namestringobligatorio
- languagestringobligatorio
- statusstringobligatorio
- categorystring | nullobligatorio
- wabaIdstringobligatorio
- componentsobject[]obligatorio
- rejectedReasonstring | nullobligatorio
- qualityRatingstring | nullobligatorio
- requestedCategorystring | nullobligatorio
- pendingCategoryobject | nullobligatorio
- categorystringobligatorio
- effectiveAtstring | nullobligatorio
- createdVia"api" | "panel" | nullobligatorio
- createdBystring | nullobligatorio
- descriptionstring | nullobligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida. `feature_disabled`: La función está desactivada en el workspace.
- 409 `conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
- 503 `unavailable`: Servicio no disponible temporalmente.
get/api/v1/conversations/{id}/capabilitiesconversations:readDisponibilidad del canal y ventana de respuesta WhatsApp.
Consulta informativa: el envío vuelve a validar integración, ventana, cuota, saldo y proveedor. La ventana abre con el último mensaje del contacto, nunca con un mensaje saliente. SMS y Telegram no requieren plantilla ni ventana.
Respuesta 200 · { data }
- conversationIdstringobligatorio
- channel"whatsapp" | "sms" | "telegram"obligatorio
- checkedAtstring (date-time)obligatorio
- phoneNumberIdstring | nullobligatorio
- configuredbooleanobligatorio
- canSendbooleanobligatorio
- reasonstring | nullobligatorio
- canSendDirectbooleanobligatorio
- canSendTemplatebooleanobligatorio
- supportedMessageTypesstring[]obligatorio
- windowobject | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- expiresAtstring (date-time) | nullobligatorio
- openbooleanobligatorio
- remainingSecondsintegerobligatorio
- templateRequiredbooleanobligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
get/api/v1/conversationsconversations:readListar conversaciones
Las del workspace (no los buzones privados), por último mensaje. Con el workspace bloqueado por el límite de contactos responde 402 `contact_limit_exceeded` (exportar). Con canales limitados, solo las de los recursos del alcance (las de otro canal responden 404 en todas las rutas de conversación); con más de 30 recursos que listar, 400 `invalid_request` con `details.reason: "channel_scope_too_large"`: filtra por `channel`.
Respuesta 200 · { data: [ … ], nextCursor }
- idstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- statusstringobligatorio
- leadIdstring | nullobligatorio
- contactNamestring | nullobligatorio
- contactHandlestring | nullobligatorio
- assigneeEmailstring | nullobligatorio
- assigneeNamestring | nullobligatorio
- lastMessageAtstring (date-time) | nullobligatorio
- lastMessagePreviewstring | nullobligatorio
- lastMessageBystring | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- awaitingReplybooleanobligatorio
- unreadCountintegerobligatorio
- botActivebooleanobligatorio
- handoffOpenbooleanobligatorio
- openTicketIdstring | nullobligatorio
- snoozedUntilstring (date-time) | nullobligatorio
- revintegerobligatorio
- createdAtstring (date-time) | nullobligatorio
- updatedAtstring (date-time) | nullobligatorio
- fromUserIdstring | nullobligatorio
Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.
- fromUsernamestring | nullobligatorio
Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
get/api/v1/conversations/{id}conversations:readLeer una conversación
Respuesta 200 · { data }
- idstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- statusstringobligatorio
- leadIdstring | nullobligatorio
- contactNamestring | nullobligatorio
- contactHandlestring | nullobligatorio
- assigneeEmailstring | nullobligatorio
- assigneeNamestring | nullobligatorio
- lastMessageAtstring (date-time) | nullobligatorio
- lastMessagePreviewstring | nullobligatorio
- lastMessageBystring | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- awaitingReplybooleanobligatorio
- unreadCountintegerobligatorio
- botActivebooleanobligatorio
- handoffOpenbooleanobligatorio
- openTicketIdstring | nullobligatorio
- snoozedUntilstring (date-time) | nullobligatorio
- revintegerobligatorio
- createdAtstring (date-time) | nullobligatorio
- updatedAtstring (date-time) | nullobligatorio
- fromUserIdstring | nullobligatorio
Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.
- fromUsernamestring | nullobligatorio
Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
get/api/v1/conversations/{id}/messagesconversations:readMensajes de una conversación
Del más reciente al más antiguo, sin notas internas.
Parámetros
- idruta · stringobligatorio
`{canal}__{id}` (p. ej. `whatsapp__573001234567`).
- limitconsulta · string
Elementos por página (1–100, por defecto 50).
- cursorconsulta · string
`nextCursor` de la página anterior (opaco).
Respuesta 200 · { data: [ … ], nextCursor }
- idstringobligatorio
- direction"inbound" | "outbound"obligatorio
- textstringobligatorio
- subjectstring | nullobligatorio
Solo correo.
- atstring (date-time) | nullobligatorio
- senderobjectobligatorio
- type"contact" | "user" | "bot" | "automation" | "api"obligatorio
- emailstring | nullobligatorio
- messageTypestring | null
- deliveryStatusstring | null
- errorobject | null
Solo WhatsApp: por qué falló, cuando `deliveryStatus` es `failed` (el mismo `error` que el evento `message.status`); `null` si no hay error.
- codestring | nullobligatorio
Código de Meta, p. ej. `131042`.
- titlestring | nullobligatorio
Título que da Meta, p. ej. «Business eligibility payment issue».
- replyToMessageIdstring | null
- interactionobject | null
- typestringobligatorio
- idstring | nullobligatorio
- titlestring | nullobligatorio
- descriptionstring | nullobligatorio
- attachmentobject | nullobligatorio
- kindstringobligatorio
- urlstring | nullobligatorio
- namestring | nullobligatorio
- templateobject | null
Solo WhatsApp saliente: la plantilla que se envió y lo que vio el contacto, para pintar la burbuja como el Buzón («Plantilla · nombre» + cuerpo + pie + botones). `null` si el mensaje no es una plantilla. En los mensajes anteriores a guardar la vista de la plantilla solo llegan `name` y `language` (sin cuerpo, cabecera, pie ni botones): el texto sigue en `text`.
- namestringobligatorio
Nombre de la plantilla en Meta, p. ej. `be_pedir_resena_v2`.
- languagestring | nullobligatorio
Idioma con el que se envió, p. ej. `es`.
- headerstring | nullobligatorio
Texto de la cabecera, con sus variables ya sustituidas; `null` si no tiene o no es de texto (imagen, vídeo, documento o ubicación).
- bodystring | nullobligatorio
Cuerpo tal como lo vio el contacto, sin cabecera ni pie. `null` si no se guardó: entonces el texto es `text` (que puede llevar cabecera y pie juntos).
- footerstring | nullobligatorio
Pie de la plantilla; `null` si no tiene o no se guardó.
- buttonsobject[]obligatorio
Botones en su orden. Los de copiar código y OTP salen sin el código (no se expone).
- kind"url" | "phone" | "quick_reply" | "copy_code" | "otp" | "other"obligatorio
- labelstringobligatorio
Texto del botón, p. ej. «Dejar mi opinión».
- urlstring | nullobligatorio
Solo `url`: enlace http(s) con su variable ya sustituida; `null` si no se sabe.
- phonestring | nullobligatorio
Solo `phone`: teléfono (`+` y dígitos).
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/conversations/{id}/replyconversations:writeResponder
Texto por el canal de la conversación y SIEMPRE desde su recurso (número, buzón o bot; una conversación de otro canal que el de la credencial responde 404) (WhatsApp: dentro de la ventana de 24 h; fuera, `template`). Cuota de cada canal: WhatsApp y correo del plan, SMS del saldo (402). 201 enviado; 202 correo encolado. 409 `unknown_outcome`: el proveedor no respondió y el mensaje pudo salir; con la misma Idempotency-Key se repite esa respuesta sin reenviar. 403 `forbidden` (`sending_paused`): el envío de correo del workspace está pausado. 402 `contact_limit_exceeded`: el workspace superó su límite de contactos (contestar a mano desde el panel sigue permitido).
Parámetros
- idruta · stringobligatorio
`{canal}__{id}` (p. ej. `whatsapp__573001234567`).
- Idempotency-Keycabecera · string
Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.
Cuerpo
- textstring
- templateobject
- messageobject | object | object | object | object
Solo WhatsApp: texto, plantilla, imagen, audio, botones, lista o enlace CTA.
- type"text"obligatorio
- textstringobligatorio
- previewUrlboolean
Respuesta 201 · { data }
- conversationIdstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- messageIdstring | nullobligatorio
- status"sent" | "queued"obligatorio
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 402 `contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla). `quota_exceeded`: Cuota mensual del plan agotada: reintentar no lo arregla.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta. `forbidden`: Operación no permitida.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `invalid_state`: Operación no válida en el estado actual. `unknown_outcome`: El proveedor no respondió y el mensaje pudo salir. No reintentes con otra Idempotency-Key: podría duplicarse. `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
- 503 `unavailable`: Servicio no disponible temporalmente.
post/api/v1/conversations/{id}/assignconversations:writeAsignar
Parámetros
- idruta · stringobligatorio
`{canal}__{id}` (p. ej. `whatsapp__573001234567`).
- Idempotency-Keycabecera · string
Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.
Respuesta 200 · { data }
- idstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- statusstringobligatorio
- leadIdstring | nullobligatorio
- contactNamestring | nullobligatorio
- contactHandlestring | nullobligatorio
- assigneeEmailstring | nullobligatorio
- assigneeNamestring | nullobligatorio
- lastMessageAtstring (date-time) | nullobligatorio
- lastMessagePreviewstring | nullobligatorio
- lastMessageBystring | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- awaitingReplybooleanobligatorio
- unreadCountintegerobligatorio
- botActivebooleanobligatorio
- handoffOpenbooleanobligatorio
- openTicketIdstring | nullobligatorio
- snoozedUntilstring (date-time) | nullobligatorio
- revintegerobligatorio
- createdAtstring (date-time) | nullobligatorio
- updatedAtstring (date-time) | nullobligatorio
- fromUserIdstring | nullobligatorio
Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.
- fromUsernamestring | nullobligatorio
Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/conversations/{id}/closeconversations:writeCerrar
Parámetros
- idruta · stringobligatorio
`{canal}__{id}` (p. ej. `whatsapp__573001234567`).
- Idempotency-Keycabecera · string
Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.
Respuesta 200 · { data }
- idstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- statusstringobligatorio
- leadIdstring | nullobligatorio
- contactNamestring | nullobligatorio
- contactHandlestring | nullobligatorio
- assigneeEmailstring | nullobligatorio
- assigneeNamestring | nullobligatorio
- lastMessageAtstring (date-time) | nullobligatorio
- lastMessagePreviewstring | nullobligatorio
- lastMessageBystring | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- awaitingReplybooleanobligatorio
- unreadCountintegerobligatorio
- botActivebooleanobligatorio
- handoffOpenbooleanobligatorio
- openTicketIdstring | nullobligatorio
- snoozedUntilstring (date-time) | nullobligatorio
- revintegerobligatorio
- createdAtstring (date-time) | nullobligatorio
- updatedAtstring (date-time) | nullobligatorio
- fromUserIdstring | nullobligatorio
Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.
- fromUsernamestring | nullobligatorio
Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.
post/api/v1/conversations/{id}/reopenconversations:writeReabrir
Parámetros
- idruta · stringobligatorio
`{canal}__{id}` (p. ej. `whatsapp__573001234567`).
- Idempotency-Keycabecera · string
Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.
Respuesta 200 · { data }
- idstringobligatorio
- channel"whatsapp" | "telegram" | "sms" | "email" | "whatsapp_group"obligatorio
- statusstringobligatorio
- leadIdstring | nullobligatorio
- contactNamestring | nullobligatorio
- contactHandlestring | nullobligatorio
- assigneeEmailstring | nullobligatorio
- assigneeNamestring | nullobligatorio
- lastMessageAtstring (date-time) | nullobligatorio
- lastMessagePreviewstring | nullobligatorio
- lastMessageBystring | nullobligatorio
- lastInboundAtstring (date-time) | nullobligatorio
- awaitingReplybooleanobligatorio
- unreadCountintegerobligatorio
- botActivebooleanobligatorio
- handoffOpenbooleanobligatorio
- openTicketIdstring | nullobligatorio
- snoozedUntilstring (date-time) | nullobligatorio
- revintegerobligatorio
- createdAtstring (date-time) | nullobligatorio
- updatedAtstring (date-time) | nullobligatorio
- fromUserIdstring | nullobligatorio
Solo WhatsApp: BSUID del contacto (`US.1349…`), también cuando no hay teléfono. `null` en otros canales o si aún no se conoce.
- fromUsernamestring | nullobligatorio
Solo WhatsApp: nombre de usuario del contacto (sin `@`), si adoptó uno.
Errores
- 400 `invalid_request`: Petición inválida (cuerpo, parámetros o consulta).
- 401 `unauthorized`: Falta la clave, no existe, está revocada o caducó.
- 403 `insufficient_scope`: La clave no tiene el alcance que exige la ruta.
- 404 `not_found`: No existe (o no es de este workspace).
- 409 `rev_mismatch`: Otro cambio llegó antes (`expectedRev` desactualizado). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.
- 422 `idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.
- 429 `rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.
- 500 `internal`: Error interno.