API Oficial (CALLING)

Contexto

WhatsApp Business Calling agrega el canal de comunicación VoIP además de la mensajería de texto entre consumidores y empresas. Los consumidores usan la aplicación de WhatsApp como en las llamadas entre consumidores, mientras que la empresa interactúa con la API de WhatsApp a través de la Graph API para la señalización y conexión inicial de la llamada.

Propuesta de valor

WhatsApp Business Calling permite a las empresas iniciar y recibir llamadas con usuarios de WhatsApp usando Voz sobre Protocolo de Internet (VoIP), con alcance global.

Nota: * Funcionalidad planificada o en desarrollo. Consulta con tu contacto de Meta o partner para más detalles.

Arquitectura

Configuraciones posibles de señalización y media

Notas:

1. También puedes usar SDES en lugar de ICE+DTLS con señalización Graph API + Webhooks.
2. Códecs de audio adicionales soportados: PCMA, PCMU.

Comenzar

Requisitos previos

1. Tu número de negocio debe estar en uso con Cloud API (no la app de WhatsApp Business).
2. Suscribe tu app al campo de webhook calls (a menos que planees usar SIP).
3. La misma app debe estar suscrita a la cuenta de WhatsApp Business de tu número de teléfono.
4. La app debe tener permisos de mensajería (whatsapp_business_messaging) para el número de negocio.
5. El negocio debe tener un límite de mensajería diario de al menos 2,000 destinatarios únicos.
6. Habilita las funciones de llamadas en tu número de teléfono de negocio.

Configurar las funciones de llamadas

La API ofrece funciones que afectan cuándo y cómo aparecen las funciones de llamada a los usuarios en tu perfil de WhatsApp:

• Control de llamadas entrantes: permite evitar que los usuarios realicen llamadas desde tu perfil de negocio.
• Horario de llamadas del negocio: evita llamadas perdidas y dirige a los usuarios a mensajear cuando tu centro de llamadas está cerrado.
• Solicitudes de callback: ofrecen al usuario la opción de solicitar un callback cuando no respondes o si tu centro de llamadas está cerrado.

Hacer y recibir llamadas

Cloud API Calling ofrece dos rutas de inicio de llamadas:

• Llamadas iniciadas por el usuario: llamadas realizadas desde un usuario de WhatsApp a tu negocio.
• Llamadas iniciadas por el negocio: llamadas realizadas desde tu negocio a un usuario de WhatsApp.

Pruebas y cuentas sandbox

Advertencia: las cuentas sandbox solo están disponibles para Tech Partners.

Información general

Una cuenta sandbox de WhatsApp es una cuenta de WhatsApp Business simulada que puedes usar para probar tu integración con la Calling API. Usa una cuenta sandbox de calling para probar lo siguiente:

• Iniciar y recibir llamadas con la Calling API.
• Validar eventos de webhook de llamadas.
• Simular flujos de onboarding sin crear activos de negocio reales.

Límites de llamadas de las cuentas sandbox

Los siguientes límites corresponden a las cuentas sandbox. Están sujetos a cambios.

Configurar una cuenta sandbox

Paso 1. Reclamar una cuenta sandbox

Sigue las instrucciones en Embedded Signup Overview — Claiming sandbox accounts para reclamar tu cuenta sandbox.

Paso 2. Obtener credenciales e identificadores de tu cuenta sandbox

1. En el App Dashboard, navega a tu app y selecciona WhatsApp > Embedded Signup Builder en la barra lateral.
   • Nota: mantén esta pestaña abierta, la usarás varias veces durante este proceso.
2. Asegúrate de que el menú desplegable Features esté vacío y haz clic en Login with Facebook.
3. Se mostrará un popup con la experiencia de Embedded Signup. En Business portfolio, selecciona Sandbox Business.
4. Completa el resto de la información requerida y haz clic en Next.
5. En la siguiente pantalla, en el menú desplegable Create or Select a WhatsApp Business Profile, selecciona Test Number.
6. Cuando el flujo de login finalice, en la sección Exchange Token, haz clic en Get Token.
   • Nota: conserva este token para el uso futuro de la API de la cuenta sandbox.
7. En la sección Fetch Shared WhatsApp Business account, haz clic en Fetch WABA details.
8. En el campo WhatsApp Business account, copia el Value de la fila id.
   • Nota: conserva este ID, es el ID de la cuenta de WhatsApp Business para la WABA sandbox.
9. En la sección Fetch phone numbers, haz clic en Fetch phone numbers.
10. En ID, copia el valor.
    • Nota: conserva este ID, es el ID de número de teléfono del número de prueba de tu cuenta sandbox.

Paso 3. Registrar tu número de teléfono de prueba y suscribirte a tu WABA

Prerrequisitos

Asegúrate de tener la siguiente información de los pasos anteriores:

• El token de tu cuenta sandbox
• El ID de WABA de tu cuenta sandbox
• El ID de tu número de teléfono de prueba

Para completar estos pasos usarás la herramienta Graph API Explorer.

• Nota: mantén esta ventana abierta, ya que usarás la configuración creada más adelante en esta guía.

1. Navega a la herramienta Graph API Explorer.
2. Asegúrate de estar en la última versión de la API.
3. Haz clic en Generate Access Token y sigue las indicaciones.
4. En Permissions, agrega los permisos whatsapp_business_management y whatsapp_business_messaging.
5. En el constructor de endpoints, ingresa /<YOUR_SANDBOX_WABA_ID>/subscribed_apps y haz clic en Submit.

{
  "success": true
}

6. A continuación, registra tu número de teléfono de prueba ingresando /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/register en el constructor de endpoints.
7. En la barra lateral izquierda, haz clic en JSON, ingresa el siguiente cuerpo JSON y haz clic en Submit:

{
  "messaging_product": "whatsapp",
  "pin": "123456"
}

8. Deberías recibir una respuesta estándar success:

{
  "success": true
}

Paso 4. Probar tu funcionalidad de mensajería

1. En la herramienta Graph API Explorer, ingresa /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/messages en el constructor de endpoints.
2. En la barra lateral izquierda, haz clic en JSON, ingresa el siguiente cuerpo JSON y haz clic en Submit:

{
  "messaging_product": "whatsapp",
  "to": "YOUR_NUMBER", // Reemplaza este valor con el número de teléfono de tu dispositivo.
  "recipient": "US.13491208655302741918",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

Nota: Usernames e IDs de usuario con ámbito de negocio: el campo recipient te permite identificar al usuario de WhatsApp por su BSUID en lugar de, o además de, su número de teléfono en to. Para más detalles, consulta Business-scoped user IDs.

3. Recibirás una respuesta con el valor "message_status": "accepted" y deberías recibir un mensaje de texto en tu dispositivo.

Paso 5. Configurar webhooks y permisos

• Navega al App Dashboard.
• Haz clic en la app que usas con WhatsApp.
• Selecciona Use cases (ícono de lápiz) en la barra lateral.
• En Connect with customers through WhatsApp, haz clic en Customize.
• En la barra lateral izquierda, haz clic en Configuration.
• En Callback URL, agrega la URL de callback de tu servidor de webhooks.
  • Si no tienes un servidor de webhooks, puedes seguir nuestras instrucciones para crear un servidor de webhooks de prueba.
• En Verify token, agrega una cadena de verificación arbitraria.
• Haz clic en Verify and save.
• En la siguiente página, en el menú desplegable Select product, haz clic en WhatsApp Business Account.
• En Webhook fields, en la fila calls, haz clic en el toggle para suscribirte al campo de webhook calls.

Finalizar: habilitar las funciones de llamada en tu número de teléfono de prueba

1. En la herramienta Graph API Explorer, ingresa /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/settings en el constructor de endpoints.
2. En la barra lateral izquierda, haz clic en JSON, ingresa el siguiente cuerpo JSON y haz clic en Submit:

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED"
  }
}

3. Deberías recibir una respuesta estándar success:

{
  "success": true
}

4. Finalmente, en Access Token, copia el access token para uso futuro.
   • Nota: conserva este access token, lo usarás para hacer llamadas a la API para probar tu integración con la Calling API.

Probar las llamadas iniciadas por el negocio

Antes de poder probar las llamadas iniciadas por el negocio (BIC), debes otorgar permisos de llamada de usuario a tu cuenta sandbox.

Puedes hacerlo en el dispositivo cliente que usas para las pruebas:

1. En tu dispositivo cliente, abre WhatsApp.
2. Navega al hilo de mensajes que tienes con tu número de teléfono de negocio sandbox.
3. En la parte superior de la pantalla, toca el número de teléfono de negocio sandbox.
4. Desplázate hacia abajo y toca Business Calling Permission.
5. Toca Allow calls.

Ahora puedes usar tu integración de Calling API para llamar al dispositivo cliente y probar tu integración.

Más información sobre las llamadas iniciadas por el negocio.

Probar las llamadas iniciadas por el usuario

Puedes probar las llamadas iniciadas por el usuario (UIC) en el dispositivo cliente que usas para las pruebas:

1. En tu dispositivo cliente, abre WhatsApp.
2. Navega al hilo de mensajes que tienes con tu número de teléfono de negocio sandbox.
3. Toca el ícono de teléfono en la parte superior de la pantalla para llamar al número de teléfono de negocio sandbox.
4. Confirma que la llamada se conecta correctamente.

Más información sobre las llamadas iniciadas por el usuario.

Disponibilidad

Llamadas iniciadas por el usuario

Disponibles en todas las ubicaciones donde Cloud API está disponible.

Llamadas iniciadas por el negocio

Disponibles en todas las ubicaciones donde Cloud API está disponible, excepto en los siguientes países:

• Estados Unidos
• Canadá
• Egipto
• Vietnam
• Nigeria

Nota: el código de país del número de teléfono del negocio debe estar en esta lista soportada. El número del consumidor puede ser de cualquier país donde Cloud API esté disponible.

Changelog

Configuración de llamadas

Utiliza estas APIs para ver y gestionar la configuración de llamadas de los números de teléfono de tu empresa. Por defecto, las llamadas no están habilitadas en un número de teléfono del negocio.

Actualizar configuración

Actualiza la configuración de llamadas de un número de teléfono: habilita o deshabilita la función, controla la visibilidad del ícono, define el horario de atención y las anulaciones por días festivos.

Endpoint: POST /calls/{v}/{did}/settings

Request:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/calls/v21.0/{did}/settings' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "ENABLED",
      "call_icon_visibility": "DEFAULT",
      "call_icons": {
        "restrict_to_user_countries": ["US", "BR"]
      },
      "call_hours": {
        "status": "ENABLED",
        "timezone_id": "America/Manaus",
        "weekly_operating_hours": [
          {
            "day_of_week": "MONDAY",
            "open_time": "0400",
            "close_time": "1020"
          },
          {
            "day_of_week": "TUESDAY",
            "open_time": "0108",
            "close_time": "1020"
          }
        ],
        "holiday_schedule": [
          {
            "date": "2026-01-01",
            "start_time": "0000",
            "end_time": "2359"
          }
        ]
      },
      "callback_permission_status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [
          {
            "hostname": "sip.example.com",
            "port": 5061,
            "request_uri_user_params": {
              "KEY1": "VALUE1"
            }
          }
        ]
      },
      "audio": {
        "additional_codecs": ["PCMA", "PCMU"]
      },
      "voicemail": {
        "status": "ENABLED",
        "triggers": ["REJECT", "TIMEOUT"],
        "audio": {
          "default": {
            "announcement_media_id": 938884519013664,
            "timeout_seconds": 20
          }
        }
      }
    }
  }'

Response (200):

{
  "success": true
}

Parámetros del nodo calling:

Nota sobre la propagación de la configuración: después de actualizar la configuración, los usuarios de WhatsApp pueden tardar hasta 7 días en reflejar los cambios. La mayoría refresca mucho antes. Puedes forzar un refresco inmediato abriendo el chat del negocio y la página de información. Independientemente del comportamiento del cliente, el servidor siempre respeta la configuración.

Comportamiento de la visibilidad del ícono:

• DEFAULT: el ícono de llamada se muestra en todos los puntos de entrada (menú del chat e información del negocio).

• DISABLE_ALL: el ícono se oculta en el menú del chat y en la ventana de información del negocio. Todos los puntos de entrada externos al chat también se desactivan. Aún puedes enviar mensajes interactivos o plantillas con un botón de llamada (Call CTA).

• Horario de llamadas (call_hours): las llamadas fuera del horario configurado (o dentro de los períodos de vacaciones/indisponibilidad) se bloquean. La pantalla de error del cliente muestra la opción de chatear con el negocio, solicitar una devolución de llamada (si está habilitada) y el próximo horario disponible.

• Permisos de devolución de llamada (callback_permission_status): una llamada iniciada por la empresa requiere permisos explícitos del usuario. La cuenta puede configurarse para activar automáticamente la interfaz de solicitud de permiso tras una llamada iniciada por el usuario que no haya sido respondida. El usuario puede modificar su selección en cualquier momento.

• Cambio planificado (ETA junio 2025) — permisos proactivos: la aplicación cliente enviará automáticamente un permiso de llamada aprobado cuando el usuario inicie una llamada a la empresa, independientemente del resultado. El usuario podrá modificar esta selección en cualquier momento. Este cambio es transparente desde el punto de vista de la integración.

Errores:

Obtener configuración

Endpoint: GET /calls/{v}/{did}/settings

Opcionalmente, puedes incluir las credenciales SIP en la respuesta con el query param include_sip_credentials=true:

GET /calls/{v}/{did}/settings?include_sip_credentials=true

Response (200):

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0400",
          "close_time": "1020"
        }
      ],
      "holiday_schedule": []
    },
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    },
    "audio": {
      "additional_codecs": ["PCMA", "PCMU"]
    },
    "voicemail": {
      "status": "ENABLED",
      "triggers": ["REJECT", "TIMEOUT"],
      "audio": {
        "default": {
          "announcement_media_id": 938884519013664,
          "timeout_seconds": 20
        }
      }
    }
  }
}

Response con restricciones: si tu negocio tiene restricciones aplicadas, la respuesta incluye el objeto restrictions:

{
  "calling": {
    "status": "ENABLED",
    "restrictions": {
      "restrictions_list": [
        {
          "type": "RESTRICTED_BUSINESS_INITIATED_CALLING",
          "reason": "Business initiated calling capability has been temporarily disabled for this phone number due to high negative feedback from users.",
          "expiration": 1754072386
        }
      ]
    }
  }
}

Los valores posibles de type son RESTRICTED_BUSINESS_INITIATED_CALLING o RESTRICTED_USER_INITIATED_CALLING. expiration es la marca de tiempo Unix UTC en que expira la restricción.

Buzón de voz (voicemail)

Cuando el buzón de voz está habilitado, Cloud API:

1. Espera el retraso configurado o una señal de rechazo tuya.
2. Responde automáticamente la llamada.
3. Reproduce un anuncio de audio.
4. Graba el mensaje de voz del llamador.
5. Entrega el buzón como mensaje de audio vía webhook.

Nota: cuando el buzón de voz está habilitado, desactiva el horario de llamadas (call_hours), porque los usuarios de WhatsApp no pueden llamar fuera del horario comercial. Las llamadas deben estar habilitadas en el número para que la configuración de voicemail tenga efecto.

Subir el media del anuncio

Los archivos de anuncio del buzón de voz deben subirse por la Media Upload API con use_case=call_voicemail_announcement, lo que los exime del TTL de 30 días estándar:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/{v}/{did}/media' \
  --header 'Authorization: Bearer <token>' \
  -F 'file=@<FILE_PATH>;type=audio/ogg' \
  -F 'messaging_product=whatsapp' \
  -F 'use_case=call_voicemail_announcement' \
  -F 'description="Default announcement (English)"'

Requisitos del media: duración menor a 60 segundos, MIME audio/ogg con códec OPUS. Los media subidos con este use_case solo pueden usarse como anuncio de buzón de voz, no como mensaje regular.

Webhooks de buzón de voz

Cuando un usuario deja un mensaje de voz, Cloud API entrega el audio por el campo de webhook messages como un mensaje de audio entrante. La diferencia con un mensaje de audio regular: messages[].id contiene el ID de la llamada (WACID) que produjo el buzón, no un WAMID. Usa ese ID para correlacionar el buzón con el ciclo de vida de la llamada.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "contacts": [
              {
                "wa_id": "<USER_PHONE_NUMBER>",
                "profile": { "name": "<USER_PROFILE_NAME>" }
              }
            ],
            "messages": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyASG...",
                "from": "<USER_PHONE_NUMBER>",
                "timestamp": "1728932177",
                "type": "audio",
                "audio": {
                  "id": "1002764438271669",
                  "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                  "mime_type": "audio/ogg; codecs=opus"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

La entrega es best-effort: si falla la recolección, no se envía webhook de buzón para esa llamada. No requiere suscripción adicional más allá del campo messages estándar.

Webhooks de actualización de ajustes

Suscríbete al campo de webhook account_settings_update para recibir notificaciones sobre actualizaciones de los ajustes del número. Actualmente solo se observan cambios en los campos de llamadas: status, call_icon_visibility, callback_permission_status, sip.status y srtp_key_exchange_protocol.

Requisitos: suscríbete al campo account_settings_update, la app debe estar suscrita a la WABA del número, y tener permiso whatsapp_business_management.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "timestamp": "1671644824",
            "type": "phone_number_settings",
            "phone_number_settings": {
              "phone_number_id": "phone-number-id",
              "calling": {
                "status": "ENABLED",
                "call_icon_visibility": "DEFAULT",
                "callback_permission_status": "ENABLED"
              }
            }
          },
          "field": "account_settings_update"
        }
      ]
    }
  ]
}

Restricciones de llamadas por feedback de usuarios

Si tus llamadas reciben feedback negativo alto (bloqueos y reportes), la funcionalidad de llamadas iniciadas por el negocio, por el usuario, o ambas, puede restringirse.

Advertencia temprana

Se notifica cuando el número está cerca de ser pausado, vía email y webhook account_update:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1623862418,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PN",
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "LOW_BUSINESS_INITIATED_CALLING_QUALITY"
            }
          }
        }
      ]
    }
  ]
}

Pausa de la funcionalidad

Cuando el feedback negativo alcanza el umbral, Cloud API restringe automáticamente la funcionalidad por 7 días. Mientras está pausada:

• Llamadas iniciadas por el negocio: no puede hacer llamadas al usuario ni enviar solicitudes de permiso.
• Llamadas iniciadas por el usuario: no puede recibir llamadas ni mostrar el ícono de llamada.

Los permisos aprobados o rechazados por los usuarios mientras está pausado siguen siendo válidos.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PN",
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
              {
                "restriction_type": "RESTRICTED_BUSINESS_INITIATED_CALLING",
                "expiration": 1641848057
              }
            ]
          }
        }
      ]
    }
  ]
}

Restricciones por baja tasa de respuesta

Cuando las llamadas entrantes no se responden con frecuencia, se notifica y el ícono de llamada puede ocultarse.

Advertencia: email con opciones para cambiar cómo manejas las llamadas entrantes.

Restricción: si la situación persiste, el botón de llamada se oculta de los usuarios. Para mitigarlo: identifica la causa de las llamadas no respondidas y asegura recursos suficientes, o desactiva los botones / las llamadas por WhatsApp Manager.

Webhook de advertencia:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505552771",
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "USER_INITIATED_CALLS_LOW_PICKUP_RATE",
              "remediation": "Please identify and address the cause of user-initiated calls not being picked up."
            }
          }
        }
      ]
    }
  ]
}

Webhook de restricción:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505552771",
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
              {
                "restriction_type": "RESTRICTED_USER_INITIATED_CALLING_CALL_BUTTON_HIDDEN",
                "remediation": "The call button has been hidden due to low pickup rates."
              }
            ]
          }
        }
      ]
    }
  ]
}

Llamadas iniciadas por el consumidor

La API de Calling soporta recibir llamadas realizadas por usuarios de WhatsApp a tu negocio. Tu negocio determina cuándo pueden recibirse llamadas configurando el horario de llamadas y la indisponibilidad por días festivos.

El flujo de una llamada iniciada por el usuario es:

1. El usuario llama a tu negocio — recibes el webhook Connect con un SDP Offer.
2. Pre-aceptar (recomendado) — establece la conexión de media antes de enviar media, lo que evita el recorte de audio.
3. Aceptar — una vez que la conexión WebRTC está establecida, acepta la llamada. Los medios fluyen inmediatamente tras el 200 OK.
4. Terminar — tu negocio o el usuario pueden colgar. Recibes el webhook Terminate.

Dispones de aproximadamente 30 a 60 segundos tras el webhook Connect para responder. Si tu negocio no responde, la llamada se termina en el lado del usuario con una notificación “No respondida” y se te envía un webhook de terminación.

Pre-aceptación

Responder a una llamada iniciada por el usuario mediante la pre-aceptación. Facilita la configuración de la llamada y evita el recorte de audio: establece la conexión WebRTC antes de aceptar la llamada, sin transmitir medios.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "pre_accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Aceptar

Acepta una llamada previa pre-aceptada, proporcionando el SDP del agente. La empresa dispone de un tiempo determinado (30–60 segundos) para responder a la llamada del usuario; si no responde, la llamada finaliza con “No respondida” y se envía un webhook de finalización.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "biz_opaque_callback_data": "random data"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Rechazar

Rechaza una llamada iniciada por el usuario.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "reject"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Colgar

Finaliza una llamada en curso. Debe invocarse incluso si hay un paquete RTCP BYE en la ruta de medios, para obtener precios más precisos. Cuando el consumidor finaliza la llamada, no es necesario invocar esta API; se enviará un webhook de finalización.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "terminate"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Campos comunes del body de signaling:

Llamadas a webhooks

Los webhooks de llamadas usan una estructura similar a la de mensajería. Una sección calls dentro de la sección value del webhook contiene los campos relacionados con las llamadas.

Conectar

Se envía en tiempo casi real cuando la empresa recibe una llamada entrante, e incluye la información SDP para establecer la conexión WebRTC.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315553601",
              "phone_number_id": "phone-number-id"
            },
            "contacts": [
              {
                "profile": {
                  "name": "callee name",
                  "username": "<USERNAME>"
                },
                "wa_id": "16315553602",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>"
              }
            ],
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "to_user_id": "<BSUID>",
                "to_parent_user_id": "<PARENT_BSUID>",
                "from": "16315553602",
                "event": "connect",
                "timestamp": "1671644824",
                "direction": "BUSINESS_INITIATED",
                "connection": {
                  "webrtc": {
                    "sdp": "<<RFC 8866 SDP>>"
                  }
                },
                "session": {
                  "sdp_type": "offer",
                  "sdp": "<<RFC 8866 SDP>>"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

Campos del objeto calls:

Terminada

Se envía cuando la llamada ha sido terminada por cualquier razón (consumidor cuelga o la empresa invoca terminate).

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16505553602",
              "phone_number_id": "phone-number-id"
            },
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "from": "16315553602",
                "event": "terminate",
                "direction": "BUSINESS_INITIATED",
                "biz_opaque_callback_data": "random data",
                "timestamp": "1671644824",
                "status": "COMPLETED",
                "start_time": "1671644824",
                "end_time": "1671644944",
                "duration": 120
              }
            ],
            "errors": [
              {
                "code": 222,
                "message": "ERROR_TITLE",
                "href": "ERROR_HREF",
                "error_data": {
                  "details": "ERROR_DETAILS"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

Campos relevantes:

Mensajes con CTA de llamada

Después de adoptar las funciones de Calling, puedes crear conciencia en tus clientes de dos maneras:

• Enviarles un mensaje con un botón de llamada de WhatsApp.
• Incrustar un deep link de llamada en tus superficies de marca (sitio web, aplicación, etc.).

Enviar mensaje interactivo con botón de llamada

Envía un mensaje interactivo con el botón de llamada de WhatsApp durante una ventana de atención al cliente o una conversación abierta. Cuando el usuario hace clic en el botón, se inicia una llamada de WhatsApp al número del negocio que envió el mensaje.

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "voice_call",
    "body": {
      "text": "You can call us on WhatsApp now for faster service!"
    },
    "action": {
      "name": "voice_call",
      "parameters": {
        "display_text": "Call on WhatsApp",
        "ttl_minutes": 100,
        "payload": "payload data"
      }
    }
  }
}

Reglas:

• interactive.type debe ser voice_call y interactive.body es obligatorio.
• interactive.footer no está permitido.
• to es requerido (salvo recipient); recipient (BSUID o parent BSUID) puede usarse en su lugar o además. Si se envían ambos, to tiene prioridad.
• display_text por defecto es Call now; longitud máxima de 20 caracteres.
• ttl_minutes (opcional): tiempo de vida del botón, entre 1 y 43200 (30 días). Por defecto 10080 (7 días).
• payload (opcional): cadena arbitraria para tracking. Se incluye en los webhooks connect y terminate bajo el campo cta_payload. Máximo 512 caracteres. Solo disponible para clientes de WhatsApp desde la versión 2.25.27.
• Enviar este mensaje a usuarios en versiones antiguas genera un webhook de error con código 131026.

Crear plantilla con botón de llamada

La API de plantillas soporta el botón VOICE_CALL, que activa una llamada de WhatsApp al hacer clic. Se puede usar en cualquier lugar donde sea posible el botón de número de teléfono.

Endpoint: POST /message_templates/{v}/{did}

Request:

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "language": "<LANGUAGE>",
  "components": [
    {
      "type": "BODY",
      "text": "You can call us on WhatsApp now for faster service!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "voice_call",
          "text": "Call Now",
          "ttl_minutes": 1440
        },
        {
          "type": "URL",
          "text": "Contact Support",
          "url": "https://www.example.com/support"
        }
      ]
    }
  ]
}

Reglas del botón voice_call en plantillas:

• type debe ser voice_call.
• text (opcional): la etiqueta del botón. Por defecto Call Now; máx 20 caracteres.
• ttl_minutes (opcional): tiempo de vida del botón, entre 1440 (1 día) y 43200 (30 días). Puedes sobrescribirlo al enviar el mensaje.
• No está soportado en plantillas de carrusel, autenticación, catálogo, cupón, oferta por tiempo limitado, SPM o MPM.

Enviar plantilla con botón de llamada

Envía la plantilla con botón de llamada a un usuario. Puedes sobrescribir ttl_minutes y enviar un payload de tracking.

Endpoint: POST /{v}/{did}/messages

Request:

{
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "messaging_product": "whatsapp",
  "type": "template",
  "recipient_type": "individual",
  "template": {
    "name": "wa_voice_call",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "voice_call",
        "parameters": [
          {
            "type": "ttl_minutes",
            "ttl_minutes": 100
          },
          {
            "type": "payload",
            "payload": "payload data"
          }
        ]
      }
    ]
  }
}

Parámetros del componente button:

Calling deep links

Los deep links de llamada son hipervínculos que enrutan a los usuarios de WhatsApp para llamar a tu negocio. El proceso es similar a un chat deep link, excepto que el formato es:

wa.me/call/<BUSINESS_PHONE_NUMBER>

Nota: los deep links no son soportados en los clientes de escritorio de WhatsApp.

• Incrustar deep links: úsalos para promocionar las llamadas de WhatsApp en tu sitio web, aplicación principal o un código QR.
• Enviar deep links: puedes enviar mensajes a usuarios con un deep link de llamada. Como los deep links pueden generarse por número de negocio, puedes usarlos para dirigir a los usuarios a un número diferente con voz habilitada. El formato wa.me/call/<BUSINESS_PHONE_NUMBER> es fácil de copiar, pegar y enviar, y no requiere crear una plantilla.
• Enviar payload en un deep link: puedes enviar un payload con el query string biz_payload:

wa.me/call/<BUSINESS_PHONE_NUMBER>?biz_payload=payload

Cuando un usuario llama usando el deep link con biz_payload, cualquier app suscrita al campo calls puede obtener este string en los webhooks connect y terminate bajo el campo deeplink_payload. El payload del deep link solo está disponible para clientes de WhatsApp desde la versión 2.25.27.

Códigos de error de llamadas

La mayoría de los errores tienen la siguiente forma:

{
  "error": {
    "message": "<Error Message>",
    "type": "<Exception Type>",
    "code": <Exception Code>,
    "fbtrace_id": "<Trace ID>"
  }
}

Soporte DTMF

Cloud API soporta tonos DTMF para integrar sistemas IVR. Los consumidores presionan botones en la aplicación cliente y los tonos se inyectan en el flujo RTP de WebRTC establecido como parte de la conexión VoIP.

• El flujo WebRTC cumple con RFC 4733 para la transferencia de dígitos DTMF sobre RTP.
• No existe un webhook para transmitir dígitos DTMF.
• El teclado de marcación solo admite casos de uso DTMF; no cambia ningún otro comportamiento de llamadas.
• Los valores de los tonos son dígitos del 0 al 9, # y *. La duración es de 500 ms y el intervalo entre tonos de 100 ms.

Clock rate: solo se soporta el clock rate 8000 en los SDP. Para llamadas iniciadas por el usuario, la oferta SDP incluye solo clock rate 8000. Para llamadas iniciadas por el negocio, tu oferta SDP debe usar clock rate 8000; incluso si está ausente, la API procede con 8000 contra el payload type 126. Los paquetes RTP de DTMF usan la misma base de timestamp y secuencia que los paquetes de audio regulares (no hay que preocuparse por clock rates distintos). El campo duration del paquete DTMF se calcula usando unidades de 8000 clock. La API no soporta clock rate 48000 para DTMF.

Llamadas iniciadas por la empresa

Resumen del producto

La API de Calling permite a tu negocio llamar a los usuarios de WhatsApp. El usuario controla cuándo tu negocio puede llamarle otorgando permisos de llamada a tu número de negocio.

El flujo de una llamada iniciada por el negocio es:

1. Obtener permiso del usuario para llamarle (mensaje de solicitud de permiso o callback_permission_status habilitado).
2. Iniciar la llamada con action: connect, identificando al usuario por número (to), BSUID (recipient) o ambos.
3. Establecer la conexión: recibes el webhook Connect con un SDP Answer de Cloud API y lo aplicas a tu stack WebRTC para iniciar la conexión de media. Luego recibes los webhooks de estado (RINGING, ACCEPTED, REJECTED). El webhook de estado ACCEPTED llega después de que la llamada se establece; Cloud API lo envía para auditoría de eventos.
4. Terminar la llamada: tu negocio o el usuario pueden colgar. Cuando termina, recibes el webhook Terminate.

Para realizar una llamada a un usuario, la empresa debe obtener primero el permiso del usuario. Cuando un usuario otorga permisos de llamada, pueden ser temporales o permanentes. Desde el 3 de noviembre de 2025, los permisos permanentes están disponibles: el usuario puede otorgar a un negocio un permiso continuo para llamar. El usuario puede revisar y cambiar el permiso en cualquier momento desde el perfil del negocio.

La empresa no tiene control sobre este permiso; solo el usuario puede otorgarlo o revocarlo, en cualquier momento. WhatsApp almacena los datos del permiso permanente hasta que el usuario lo revoca.

Una empresa puede obtener permiso de las siguientes maneras:

1. Enviar una solicitud de permiso de llamada al usuario — mensaje de formato libre o plantilla; el usuario elige entre temporal o permanente.
2. Permiso de devolución de llamada — el usuario otorga automáticamente un permiso temporal al llamar al negocio. Debes habilitar callback_permission_status en el número.
3. Permiso vía perfil del negocio — el usuario otorga permiso a través del perfil del negocio.

Nota: las funciones de permiso de llamada están disponibles solo en las regiones donde las llamadas iniciadas por el negocio están disponibles.

Cuando el consumidor lo otorga, un permiso de llamada permite llamar al usuario sujeto a las siguientes restricciones (por par empresa + consumidor):

Solicitud de permiso al usuario

La solicitud de permiso se envía como mensaje interactivo de formato libre o como mensaje de plantilla. El consumidor puede aprobar, rechazar o no responder; también puede cambiar su respuesta antes de que caduque.

La solicitud caduca cuando ocurre cualquiera de estos casos:

• El consumidor interactúa con una nueva solicitud de permiso subsiguiente.
• 7 días después de que el consumidor aceptó o rechazó el permiso.
• 7 días después de la entrega si el consumidor no responde.

Límites de envío:

• Máximo 1 solicitud de permiso en 24 horas y 2 solicitudes en 7 días por par. El límite se restablece con una llamada conectada entre la empresa y el consumidor.
• 2 llamadas consecutivas sin respuesta generan un mensaje del sistema para reconsiderar el permiso aprobado.
• 4 llamadas consecutivas sin respuesta revocan automáticamente el permiso aprobado.

Formas de envío:

1. Mensaje de formato libre: en respuesta a un mensaje del usuario, sujeto a la ventana de atención al cliente. El cuerpo de texto es opcional; encabezado y pie no son compatibles.
2. Mensaje de plantilla: permite iniciar una conversación con una solicitud de llamada. El cuerpo es obligatorio; admite encabezado y pie.

API: Enviar solicitud de permiso de formato libre

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<phone number> or <wa_id>",
  "recipient": "US.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "call_permission_request",
    "action": {
      "name": "call_permission_request"
    },
    "body": {
      "text": "We would like to call you to help support your query on Order No: ON-12345."
    }
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+1-408-555-1234",
      "wa_id": "14085551234",
      "user_id": "<BSUID>",
      "parent_user_id": "<PARENT_BSUID>"
    }
  ],
  "messages": [
    {
      "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    }
  ]
}

Notas:

• Solo los campos type y action.name son obligatorios. action.name debe ser call_permission_request.
• to es requerido (salvo recipient); recipient (BSUID o parent BSUID) puede usarse en su lugar o además. Si se envían ambos, to tiene prioridad.
• body es opcional y da contexto al usuario.
• La empresa no puede editar el contenido del mensaje interactivo de solicitud de permiso de llamada; solo el body.
• Requiere una ventana de atención al cliente abierta con la cuenta de usuario.
• Enviar a usuarios en versiones antiguas genera un webhook de error con código 131026.

API: Crear plantilla con solicitud de permiso

Endpoint: POST /message_templates/{v}/{did}

Request:

{
  "name": "sample_cpr_template",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "text": "Support of Order No: {{1}}",
      "example": {
        "body_text": [["ON-12345"]]
      }
    },
    {
      "type": "BODY",
      "text": "We would like to call you to help support your query on Order No: {{1}} for the item {{2}}.",
      "example": {
        "body_text": [["ON-12345", "Avocados"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Talk to you soon!"
    },
    {
      "type": "call_permission_request"
    }
  ]
}

Response (200):

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "<CATEGORY>"
}

Notas:

• El componente body es obligatorio y solo admite texto.
• Encabezado y pie son opcionales.
• Categorías soportadas: Marketing y Utilidad.
• El tipo call_permission_request identifica la plantilla.
• Los medios no son compatibles con esta plantilla.

API: Enviar plantilla de solicitud de permiso

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{user number}",
  "type": "template",
  "template": {
    "name": "sample_cpr_template",
    "language": {
      "policy": "deterministic",
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "ON-12345"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "ON-12345"
          },
          {
            "type": "text",
            "text": "Avocados"
          }
        ]
      }
    ]
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+1-408-555-1234",
      "wa_id": "+1-408-555-1234"
    }
  ],
  "messages": [
    {
      "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    }
  ]
}

API: Obtener el estado del permiso de llamada

Obtiene el estado del permiso de llamada para un número de teléfono de negocio con un único usuario de WhatsApp. Puedes identificar al usuario por su número (user_wa_id) o por su BSUID (recipient).

Endpoint: GET /calls/{v}/{did}/call_permissions?user_wa_id={user_whatsapp_id}

O usando un BSUID:

Endpoint: GET /calls/{v}/{did}/call_permissions?recipient={BSUID}

Response (200):

{
  "messaging_product": "whatsapp",
  "permission": {
    "status": "temporary",
    "expiration_time": 1745343479
  },
  "actions": [
    {
      "action_name": "send_call_permission_request",
      "can_perform_action": true,
      "limits": [
        {
          "time_period": "PT24H",
          "max_allowed": 1,
          "current_usage": 0
        },
        {
          "time_period": "P7D",
          "max_allowed": 2,
          "current_usage": 1
        }
      ]
    },
    {
      "action_name": "start_call",
      "can_perform_action": false,
      "limits": [
        {
          "time_period": "PT24H",
          "max_allowed": 5,
          "current_usage": 5,
          "limit_expiration_time": 1745622600
        }
      ]
    }
  ]
}

Campos de la respuesta:

Errores:

Webhooks de permiso de llamada

Aprobación temporal

Cuando el consumidor aprueba un permiso temporal, la sección interactive del webhook de mensajes contiene call_permission_reply.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "{phone-number-id}",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "{phone-number}",
              "phone_number_id": "{phone-number-id}"
            },
            "contacts": [
              {
                "profile": { "name": "NAME" },
                "wa_id": "{phone-number}"
              }
            ],
            "messages": [
              {
                "from": "{phone-number}",
                "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
                "timestamp": "{TIMESTAMP}",
                "context": {
                  "from": "{phone-number}",
                  "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
                },
                "interactive": {
                  "type": "call_permission_reply",
                  "call_permission_reply": {
                    "response": "accept",
                    "is_permanent": false,
                    "expiration_timestamp": "{timestamp}",
                    "response_source": "user_action"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Aprobación permanente

Igual que la aprobación temporal, con is_permanent: true y sin expiration_timestamp.

Rechazo

Igual que la aprobación, con response: "reject". response_source puede ser user_action (el usuario rechazó) o automatic (rechazo automático por límites de llamadas no contestadas).

Permiso desde el flujo de callback

Cuando el permiso se otorga tras una llamada iniciada por el consumidor perdida, el context.id contiene el ID de llamada de la llamada perdida.

Campos de call_permission_reply:

Iniciar una nueva llamada

Inicia una llamada a un usuario de WhatsApp. Hay un límite de 10,000 llamadas nuevas por 24 horas por número de teléfono de negocio.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "biz_opaque_callback_data": "0fS5cePMok"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "calls": [
    {
      "id": "wacid.ABGGFjFVU2AfAgo6V"
    }
  ]
}

Parámetros del body:

Errores:

Webhooks de estado de llamada

Se envía en determinados eventos de una llamada iniciada por la empresa: ringing (cuando la llamada comienza a sonar), accepted (el consumidor acepta) y rejected (el consumidor rechaza).

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315553601",
              "phone_number_id": "phone-number-id"
            },
            "statuses": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V",
                "timestamp": "1671644824",
                "type": "call",
                "status": "RINGING",
                "recipient_id": "16315553602",
                "biz_opaque_callback_data": "random data"
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

Campos de statuses:

Grabación de llamadas

La API de Calling puede grabar el audio de las llamadas iniciadas por el negocio (BIC) y por el usuario (UIC). Cuando optas por grabar una llamada, ambos participantes escuchan un anuncio corto obligatorio por ley antes de que comience la grabación. Después de que termina la llamada, recibes un webhook con un media ID para descargar la grabación.

La grabación es opt-in por llamada: decides al iniciar o aceptar cada llamada si se graba. Es independiente de la transcripción de llamadas: puedes habilitar una, ambas o ninguna. Cada una se configura y cobra por separado, tiene su propio objeto de request y entrega su resultado en su propio evento de webhook.

Habilitar grabación en una llamada iniciada por el negocio

Agrega un objeto recording al body de tu solicitud de llamada iniciada por el negocio:

Endpoint: POST /calls/{v}/{did}/signaling

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "recording": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Habilitar grabación en una llamada iniciada por el usuario

Agrega el mismo objeto recording al aceptar una llamada entrante:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "recording": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Para aceptar una llamada entrante sin grabarla, omite el campo recording o envíalo con "status": "DISABLED".

Anuncios y consentimiento

Antes de grabar cualquier audio, la API mezcla un anuncio hablado en los streams de audio del negocio y del usuario. El anuncio se genera a partir del string purpose y el announcement_language que proporciones, por ejemplo:

“El audio de esta llamada se grabará con el siguiente propósito: <tu propósito>.”

La grabación comienza solo después de que el anuncio termina. Un participante que no consienta puede rechazar terminando la llamada antes o durante el anuncio. El campo purpose es obligatorio cuando status es ENABLED; las llamadas con grabación habilitada pero sin propósito se rechazan con un error de request.

Referencia del objeto recording

Idiomas de anuncio soportados

Grabación con transcripción

La grabación y la transcripción son totalmente independientes. Los objetos recording y transcription son campos de request separados; eliges cada uno por llamada:

• Solo recording → audio, sin transcripción.
• Solo transcription → transcripción, sin audio.
• Ambos → audio y transcripción.
• Ninguno (o ambos DISABLED) → ninguno.

Cuando habilitas ambos en la misma llamada, los participantes escuchan un anuncio combinado:

“El audio de esta llamada se grabará y transcribirá con el siguiente propósito: <tu propósito>.”

Cuando ambos objetos están presentes, se usan announcement_language y purpose del objeto recording para el anuncio combinado; los valores correspondientes del objeto transcription se ignoran. Aun así, recibes un webhook separado por cada feature habilitada.

Webhook de grabación disponible

Después de que la llamada termina y el post-procesamiento finaliza (típicamente en menos de un minuto), la API envía un evento call_recording_available bajo el campo de webhook calls:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "calls",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>"
            },
            "calls": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyNTMVAgASGCBGO...",
                "from": "<USER_PHONE_NUMBER>",
                "from_user_id": "<BSUID>",
                "from_parent_user_id": "<PARENT_BSUID>",
                "timestamp": "1728932177",
                "event": "call_recording_available",
                "call_recording": {
                  "type": "audio",
                  "audio": {
                    "id": "1002764438271669",
                    "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                    "mime_type": "audio/ogg; codecs=opus",
                    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Campos de call_recording:

Descargar la grabación

Las grabaciones usan el mismo flujo de descarga que los mensajes de media:

1. La url del webhook es válida por 5 minutos. Emite un GET autenticado con tu access token para descargar el archivo.
2. Si la URL expiró, usa la Media API para recuperar una URL fresca con el audio.id.

Retención

Las grabaciones permanecen disponibles para descarga durante 7 días después de que se entrega el webhook call_recording_available. Después, el media ID expira y el archivo subyacente se elimina. Descarga y persiste la grabación en tu propio almacenamiento dentro de la ventana de retención si necesitas mantenerla a largo plazo.

Errores

Transcripción de llamadas

La API de Calling puede transcribir el audio de las llamadas iniciadas por el negocio (BIC) y por el usuario (UIC). Cuando optas por transcribir una llamada, ambos participantes escuchan un anuncio corto obligatorio por ley antes de que comience la transcripción. Después de que termina la llamada, recibes un webhook con un media ID para descargar la transcripción como un documento JSON.

La transcripción es opt-in por llamada: decides al iniciar o aceptar cada llamada si se transcribe. Es independiente de la grabación de llamadas: puedes habilitar una, ambas o ninguna. Cada una se configura y cobra por separado, tiene su propio objeto de request y entrega su resultado en su propio evento de webhook.

Habilitar transcripción en una llamada iniciada por el negocio

Agrega un objeto transcription al body de tu solicitud de llamada iniciada por el negocio:

Endpoint: POST /calls/{v}/{did}/signaling

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "transcription": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Habilitar transcripción en una llamada iniciada por el usuario

Agrega el mismo objeto transcription al aceptar una llamada entrante:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "transcription": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Para aceptar una llamada entrante sin transcribirla, omite el campo transcription o envíalo con "status": "DISABLED".

Anuncios y consentimiento

Antes de transcribir cualquier audio, la API mezcla un anuncio hablado en los streams de audio del negocio y del usuario:

“El audio de esta llamada se transcribirá con el siguiente propósito: <tu propósito>.”

La transcripción comienza solo después de que el anuncio termina. Un participante que no consienta puede rechazar terminando la llamada antes o durante el anuncio. El campo purpose es obligatorio cuando status es ENABLED; las llamadas con transcripción habilitada pero sin propósito se rechazan con un error de request.

Referencia del objeto transcription

Idiomas de anuncio soportados

Nota: announcement_language también acepta nl y es_ES. Son válidos, pero hasta que haya un anuncio de transcripción localizado, reproducen el anuncio en inglés.

Transcripción con grabación

La transcripción y la grabación son totalmente independientes. Cuando habilitas ambas en la misma llamada, los participantes escuchan un anuncio combinado:

“El audio de esta llamada se grabará y transcribirá con el siguiente propósito: <tu propósito>.”

Cuando ambos objetos están presentes, se usan announcement_language y purpose del objeto recording para el anuncio combinado; los valores correspondientes del objeto transcription se ignoran. Aun así, recibes un webhook separado por cada feature habilitada.

Webhook de transcripción disponible

Después de que la llamada termina y el post-procesamiento finaliza (típicamente en menos de un minuto), la API envía un evento call_transcription_available bajo el campo de webhook calls:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "calls",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>"
            },
            "calls": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyNTMVAgASGCBGO...",
                "from": "<USER_PHONE_NUMBER>",
                "from_user_id": "<BSUID>",
                "from_parent_user_id": "<PARENT_BSUID>",
                "timestamp": "1728932177",
                "event": "call_transcription_available",
                "call_transcript": {
                  "document": {
                    "id": "1002764438271669",
                    "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                    "mime_type": "application/json",
                    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Campos de call_transcript:

Idioma de la transcripción

No especificas un idioma de transcripción en el request. La API detecta automáticamente el idioma hablado, lo transcribe y lo reporta en el campo transcript.language del documento (código ISO 639, por ejemplo en). Este idioma es independiente del announcement_language.

El conjunto de idiomas detectables evoluciona constantemente e incluye (entre otros): inglés, español, portugués, francés, alemán, italiano, hindi, árabe, chino, japonés, coreano, ruso, turco, vietnamita y más de 50 idiomas. Si la llamada se habla en un idioma no soportado, igual recibes el webhook call_transcription_available, pero la transcripción puede estar vacía.

Formato del documento de transcripción

El documento descargado es un JSON con dos objetos de nivel superior: metadata (información del audio procesado) y transcript (el contenido transcrito).

{
  "metadata": {
    "processed_at": "2026-06-18T20:16:47Z",
    "audio": {
      "duration": 21.76,
      "sample_rate": 16000,
      "channels": 2,
      "audio_format": "stereo"
    }
  },
  "transcript": {
    "text": "[Business] Hello, how about you? [Customer] Hey, I'm good. How are you?",
    "language": "en",
    "duration": 21.76,
    "confidence": 0.83,
    "segments": [
      {
        "id": 1,
        "speaker": "Business",
        "channel": 0,
        "start": 1.16,
        "end": 2.44,
        "text": "Hello, how about you?",
        "confidence": 0.85,
        "words": [
          {
            "word": "Hello,",
            "start": 1.16,
            "end": 1.64,
            "confidence": 0.89,
            "lang": "en"
          }
        ]
      }
    ]
  }
}

Campos de metadata:

Campos de transcript:

Campos de segments:

Cada segmento representa un tramo continuo de habla de un hablante.

Descargar la transcripción

Las transcripciones usan el mismo flujo de descarga que los mensajes de media:

1. La url del webhook es válida por 5 minutos. Emite un GET autenticado con tu access token para descargar el archivo.
2. Si la URL expiró, usa la Media API para recuperar una URL fresca con el document.id.

Retención

Las transcripciones permanecen disponibles para descarga durante 7 días después de que se entrega el webhook call_transcription_available. Después, el media ID expira y el archivo subyacente se elimina. Descarga y persiste la transcripción en tu propio almacenamiento dentro de la ventana de retención si necesitas mantenerla a largo plazo.

Errores

Mejores prácticas de integración

Problema y solución de recorte de audio

Al conectar el segmento de medios del consumidor de WhatsApp (WebRTC) con otro segmento de medios (por ejemplo SIP), puede producirse recorte de audio: el consumidor pierde aproximadamente un segundo del mensaje del negocio (por ejemplo, un IVR que reproduce 1-2-3 puede escucharse solo desde el 2).

Causa raíz: cuando un servidor de medios conecta dos segmentos, debe asegurarse de que ambos estén aproximadamente listos al mismo tiempo. Si el segmento SIP envía medios antes de que el segmento WebRTC esté listo, los paquetes se descartan y se produce el recorte.

Solución sugerida: un agente WebRTC no debe transmitir medios hasta que el proceso ICE esté casi completo. Esto se logra con una aceptación optimista: invoca la pre-aceptación incluso antes de enviar el INVITE SIP. Según RFC, un UAC debe estar listo para recibir medios justo después de enviar el INVITE.

Puntos clave:

• Al recibir el webhook de conexión, inicializa el agente WebRTC, prepara la respuesta SDP y llama a la pre-aceptación con esa respuesta SDP.
• Espera a que el proceso ICE complete la creación de listas válidas antes de enviar medios.
• Si el UA SIP rechaza la llamada en lugar de enviar un 200 OK, llama a la API de terminación.
• Si la conexión del consumidor está lista antes que la SIP, el consumidor puede escuchar unos milisegundos de silencio, lo cual es mejor que perder el audio inicial.

Otras alternativas: forzar al UA SIP a no reproducir audio hasta recibir el ACK de WebRTC, hasta detectar el estado conectado, almacenar en búfer los paquetes SIP y enviarlos al establecer la conexión, o insertar silencio en el IVR antes del audio real.

Patrones de integración

Una app vs. múltiples apps

Para integrar la API de Calling necesitas llamar a endpoints de la Graph API y procesar webhooks de Meta, lo que requiere una app. Casi siempre ya tienes una app usada para mensajería, y puedes reutilizarla para llamadas.

En esta configuración, la URI del webhook es la misma para webhooks de mensajes y de llamadas, pero el payload del webhook permite distinguir ambas categorías. Puedes reenviar los webhooks específicos de llamadas a un componente relacionado desde tu lógica de webhook principal.

Reutilizar la misma app ofrece:

• Menor overhead operativo (revisión de app, mantenimiento continuo).
• Huella simplificada en Meta.
• Igualdad entre la app usada para Embedded Signup y la usada para invocar Graph APIs y recibir webhooks.
• Sin impacto en la funcionalidad existente; solo debes asegurar que tu servidor de webhook maneje correctamente los webhooks de llamadas.

Usar apps separadas también está soportado.

Integración con un proveedor de calling de terceros

En este escenario, usas un proveedor (vendor) de calling de terceros internamente, y ese proveedor no es visible para Meta. El patrón es similar a cualquier otro servicio SaaS. Esta arquitectura puede extenderse opcionalmente para integrarse con infraestructura SIP de tu lado.

Advertencia: nuestros términos prohíben el uso de PSTN en cualquier tramo de la llamada de WhatsApp en el flujo general. Aunque conectes la llamada de WA al mundo SIP, debes asegurarte de que siga siendo exclusivamente VoIP y nunca toque la PSTN. Un troncal SIP por sí mismo no está prohibido, porque técnicamente puede usarse sin PSTN.

Guías para la integración de la ruta de media

El stack VoIP de WhatsApp Business Calling está diseñado para ser compatible con WebRTC, pero Meta restringe las funcionalidades soportadas.

Requisitos obligatorios (si no se cumplen, la llamada falla durante la señalización o la decodificación de paquetes):

• Usa solo los códecs soportados.
• Para Opus, usa un clock rate de media de 48 kHz.
• Para Opus, usa un ptime de 20 ms.
• El audio debe usar un único SSRC. El servidor relay de Meta sobrescribe el SSRC de todos los paquetes de audio del negocio a un SSRC fijo antes de que lleguen al cliente de WA. Los clientes de WA manejan solo una fuente de audio de sus pares. Usar múltiples SSRC causa comportamiento indefinido: corrupción severa de media, glitches de audio y probablemente falla total.
• Configura el clock rate de DTMF a 8 kHz.

Recomendaciones (para alta calidad y confiabilidad):

• Proceso ICE: el stack de Meta es ICE-LITE; se recomienda que el stack del Solution Partner sea ICE-FULL (RFC 5245 §2.7). El stack del partner debe iniciar el proceso ICE enviando checks STUN, asumir el rol ICE CONTROLLING (Meta asume CONTROLLED), usar nominación regular (no agresiva) (RFC 5245 §8.1.1.2), esperar a que el ICE complete antes de nominar el candidato y comenzar DTLS, y no cambiar de candidato a mitad de la llamada.
• DTLS: usa claves ECDH para los certificados DTLS para evitar fragmentación de paquetes. El Solution Partner debe actuar como cliente DTLS (RFC 6347 §4.2).
• Media: WhatsApp puede no enviar siempre el primer paquete RTP. La salida de media de tu servidor no debe esperar a la entrada de media de WhatsApp; si lo hace, existe el riesgo de deadlock donde cada lado espera al otro.
• Recorte de audio: ver la sección de recorte de audio más arriba.

Ejemplos de integración

Meta documenta ejemplos de integración con plataformas VoIP comunes. Estas guías son solo informativas, sin soporte ni garantías de Meta ni de ningún vendor; hay muchas formas de integrar y las guías explican una sola, con fines ilustrativos.

Asterisk usando SIP

Integración de la API de Calling usando señalización SIP con Asterisk, un PBX open-source.

• Llamadas iniciadas por el usuario: el usuario de WhatsApp marca el número del negocio; la llamada llega a Asterisk y se enruta por un IVR que pide una extensión registrada en el mismo servidor; la llamada se conecta a esa extensión.
• Llamadas iniciadas por el negocio: el agente se registra en Asterisk con credenciales SIP; marca la extensión b2c-sip, el IVR pide el número de WhatsApp a llamar, y la llamada se conecta al usuario.
• El tramo WA → Asterisk usa SDES para intercambio de claves de media y Opus como códec. El tramo Asterisk → SIP UA usa SDES y Opus o G.711.

Troubleshooting clave — no recibir ACK de Meta o el audio del negocio se corta a los ~30s:

Si Meta envía un SIP INVITE, tu servidor responde 200 OK, pero nunca recibes el ACK y el servidor SIP termina el diálogo por timeout de ACK (típicamente 32s), la causa más probable son los encabezados Record-Route incorrectos en tu 200 OK. La respuesta 200 OK no debe modificar los encabezados Record-Route incluidos en el INVITE original de Meta (puedes agregar nuevos, pero no modificar los presentes). La solución es rewrite_contact=no en la configuración del endpoint de WhatsApp en pjsip.conf, y asegurar que tu 200 OK tenga como últimos 2 encabezados:

Record-Route: <sip:wa.meta.vc;transport=tls;lr>
Record-Route: <sip:onevc-sip-proxy.fbinfra.net:8191;transport=tls;lr>

FreeSWITCH usando SIP

Integración con FreeSWITCH usando señalización SIP. Misma estructura de flujo que Asterisk (IVR para extensiones y para llamadas B2C vía b2c-sip). El tramo WA → FreeSWITCH usa SDES con Opus; el tramo FreeSWITCH → SIP UA usa SDES con Opus o G.711.

Puntos clave: FreeSWITCH escucha en 5081 para TLS; el dialplan wa-biz-api-dialplan.xml verifica que la solicitud venga de wa.meta.vc y usa check_acl con la lista de IPs permitidas de Meta; se agrega un stream de silencio de 1 segundo para establecer la ruta de media y evitar recorte de audio.

FreeSWITCH usando Graph API con Janus

Integración usando la señalización de Cloud API (Graph APIs + Webhooks) con FreeSWITCH y Janus, un servidor WebRTC de propósito general.

• Un módulo de integración se sitúa entre WA y Janus y traduce los mensajes de Cloud API Signaling a mensajes del plugin SIP de Janus y viceversa.
• Janus convierte la media de WA (WebRTC, intercambio de claves DTLS) a la media negociada con FreeSWITCH (SDES).
• Llamadas iniciadas por el negocio: el SIP INVITE llega a Janus en la extensión 1000, se convierte a un request de Graph API con el SDP del INVITE como offer; cuando el usuario acepta, se acepta el SIP INVITE pasando el SDP answer del webhook connect.
• Llamadas iniciadas por el usuario: el webhook recibe la llamada entrante con el SDP offer; el plugin SIP de Janus envía un INVITE a FreeSWITCH (destino c2b-sip); al recibir el 200 OK, se envía un request accept a Meta con el SDP del answer.

Asterisk usando Graph API con RtpEngine

Integración usando la señalización de Cloud API con Asterisk y RtpEngine, un proxy para relaying y control de flujos RTP. RtpEngine actúa como proxy de media entre WA (WebRTC, DTLS) y Asterisk (SDES).

El módulo de integración traduce Cloud API Signaling a SIP para Asterisk, usa el protocolo ng de RtpEngine para el bridging de media, y conecta vía extensión 1000 reservada. Para iniciar una llamada: Asterisk envía un SIP INVITE a la extensión 1000 con un header personalizado con el número de WA; el SDP del INVITE se envía a RtpEngine, que devuelve un nuevo SDP; ese SDP se usa en el request de Graph API para iniciar la llamada.

Asterisk con WebRTC integrado usando Graph API

Similar a Asterisk + RtpEngine, pero usando el soporte WebRTC integrado de Asterisk (no requiere RtpEngine). En la configuración de la extensión 1000, webrtc=yes habilita de forma abreviada: use_avpf=yes, media_encryption=dtls, dtls_verify=fingerprint, dtls_setup=actpass, ice_support=yes, media_use_received_transport=yes, rtcp_mux=yes.

Modelo de precios

Advertencia: todas las llamadas iniciadas por el usuario son gratuitas.

Información general

Las empresas pagan por las llamadas en función de:

• La duración de la llamada (calculada en pulsos de seis segundos).
• El código de país del número de teléfono al que se llama.
• El nivel de volumen (según los minutos llamados dentro del mes calendario), usando el mismo devengo por niveles (tiering accrual) que la mensajería.

Nota: nuestros sistemas cuentan los pulsos fraccionarios como un pulso completo. Por ejemplo, una llamada de 56 segundos (9.33 pulsos) se contaría como 10 pulsos.

Para las llamadas que cruzan niveles de precios (por ejemplo, del nivel 0–50,000 al nivel 50,001–250,000), toda la llamada se cobra a la tarifa más baja (es decir, la del nivel de mayor volumen).

Se requiere un método de pago válido para realizar llamadas.

Nota: los mensajes de solicitud de permiso de llamada están sujetos a la tarificación por mensaje.

Tarjetas de tarifas y niveles de volumen

Estas tarjetas de tarifas representan las tarifas y niveles de volumen actuales de la WhatsApp Business Calling API, vigentes desde el 1 de abril de 2026, según la zona horaria de la cuenta de WhatsApp Business.

Actualizaciones de las tarjetas de tarifas

Las siguientes tablas muestran actualizaciones futuras de las tarifas. Consulta las tarjetas de tarifas actuales para ver las tarifas vigentes.

Tarifas vigentes desde el 1 de julio de 2026 en 16 monedas:

Actualizaciones anteriores

• Vigente desde el 1 de abril de 2026 – 8 nuevas monedas de facturación: AED (Emiratos Árabes Unidos), ARS (Argentina), CLP (Chile), COP (Colombia), MYR (Malasia), PEN (Perú), SAR (Arabia Saudita), SGD (Singapur).
• Vigente desde el 1 de enero de 2026 – tarifas MXN (México) introducidas.

Cómo las llamadas cambian la ventana de servicio al cliente de 24 horas

Actualmente, cuando un usuario de WhatsApp te envía un mensaje, comienza (o se refresca) un temporizador de 24 horas llamado ventana de servicio al cliente.

Cuando estás dentro de la ventana, tu negocio puede enviar cualquier tipo de mensaje al usuario de WhatsApp, algo que no está permitido de otra forma.

Con la introducción de la Calling API, la ventana de servicio al cliente ahora también comienza o se refresca con las llamadas:

• Cuando un usuario de WhatsApp te llama, sin importar si aceptas la llamada o no.
• Cuando un usuario de WhatsApp acepta tu llamada.

Obtener costos y estadísticas de llamadas

Obtén las estadísticas de llamadas de tu cuenta de WhatsApp Business (WABA), con información útil como costo, conteos de llamadas completadas y duración promedio de llamadas. Aprende más sobre call analytics.

Endpoint: GET /calls/{v}/{did}/analytics

Response (200):

{
  "call_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1676361600,
            "end": 1676448000,
            "cost": 10,
            "count": 10,
            "average_duration": 1
          }
        ]
      }
    ]
  },
  "id": "114525791557199"
}

Filtros:

Especificaciones SIP

El Protocolo de Inicio de Sesión (SIP) es un protocolo de señalización usado para iniciar, mantener, modificar y terminar sesiones de comunicación en tiempo real entre dos o más endpoints. La API de Calling soporta usar SIP como protocolo de señalización en lugar de los endpoints de la Graph API.

Precaución: al habilitar SIP en un número de teléfono comercial, no puedes usar los endpoints de la Graph API relacionados con llamadas. Por defecto, no se envían webhooks relacionados con llamadas, pero puedes habilitar la entrega de webhooks para llamadas SIP con webhook_delivery para recibir eventos del ciclo de vida.

Requisitos previos:

• La aplicación debe estar habilitada para llamadas (firma del contrato Beta).
• La aplicación debe tener permisos de mensajería en el número de teléfono comercial. Prueba enviando y recibiendo mensajes con los endpoints de Graph API, y usa la misma app para configurar tu servidor SIP. Verifica con la Health Status API.
• El modo de la aplicación debe ser “En vivo” (no “En desarrollo”).
• Un servidor SIP de terceros compatible con estándares que soporte transporte TLS y autenticación digest.

Seguridad:

• El transporte TLS es obligatorio para SIP. Meta presenta un certificado de servidor válido cuyo nombre de sujeto cubre el dominio SIP wa.meta.vc. Tu servidor SIP debe hacer lo mismo: Meta valida que tu certificado sea válido y que el nombre de sujeto cubra el dominio SIP configurado en el número.
• Meta no soporta TLS mutuo (mTLS): cuando Meta actúa como cliente TLS, tu servidor TLS no debe solicitar certificado de cliente. Si lo solicitas, Meta presentará un certificado de cliente cuyo sujeto referencia un host dinámico aleatorio que no pasará la validación.
• Meta agrega transport=TLS a la URI de solicitud en sus solicitudes SIP a tu servidor.
• Para llamadas iniciadas por el negocio, el INVITE SIP de tu servidor será desafiado con autenticación digest.
• Para llamadas iniciadas por el usuario, se recomienda fuertemente desafiar el INVITE SIP de Meta con autenticación digest.

Configurar los ajustes SIP

Endpoint: POST /calls/{v}/{did}/settings

Request:

{
  "calling": {
    "status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "webhook_delivery": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "port": 5061,
          "request_uri_user_params": {
            "tgrp": "meta-wa",
            "trunk-context": "byoc.example.com"
          }
        }
      ]
    }
  }
}

Response (200):

{
  "success": true
}

Campos de sip:

Ejemplo con curl:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/calls/v21.0/{did}/settings' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [{
          "hostname": "{SIP_SERVER_URL}"
        }]
      }
    }
  }'

Obtener la configuración SIP

La contraseña del usuario SIP se incluye solo si se especifica el query param include_sip_credentials=true.

Endpoint: GET /calls/{v}/{did}/settings?include_sip_credentials=true

Response (200):

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "app_id": "<APP_ID_THAT_CONFIGURED_THIS_SIP_SERVER>",
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    }
  }
}

Nota: el campo sip_user_password solo se incluye si se agregó el query param include_sip_credentials=true. La respuesta de GET incluye app_id, que identifica la app que configuró ese servidor SIP.

Restablecer la contraseña SIP

Para hacer que Meta genere una nueva contraseña SIP:

1. Deshabilita SIP y borra el servidor SIP.
2. Vuelve a habilitar SIP y agrega el servidor.
3. Consulta la configuración SIP con include_sip_credentials=true para ver la nueva contraseña.

# Deshabilitar y borrar
curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/calls/v21.0/{did}/settings' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "DISABLED",
      "sip": {
        "status": "DISABLED",
        "servers": []
      }
    }
  }'