API de nube

Plataforma de WhatsApp Business > API de nube > Guías

Migrar de la API local a la API de nube

En este documento, se describe cómo migrar números de teléfono de empresa de la API local a la API de nube.

Ten en cuenta que la migración de un número de teléfono de empresa de una API a otra no es igual que la migración de un número de una cuenta de WhatsApp Business (WABA) a otra.

Para hacer la migración de la API de nube a la API local, consulta Migrar de la API de nube a la API local.

Funcionamiento

El proceso de migración implica generar metadatos sobre el número de teléfono de empresa y usarlos para registrar el número para su uso con la API de nube. Esto, a su vez, anula el registro del número de teléfono de la API local, ya que un número de teléfono solo se puede registrar para su uso con una API a la vez.

La migración NO afecta a lo siguiente:

  • el nombre para mostrar, el estado de verificación ni la calificación de calidad del número de teléfono de empresa;
  • las plantillas utilizadas por el número de teléfono de empresa ni sus estados;
  • la cuenta WABA propietaria, su estado de cuenta empresarial oficial ni su límite de mensajes.

Sin embargo, antes de realizar la migración, debes conocer las diferencias entre las API y tomar las medidas necesarias antes de seguir los pasos para la migración que se describen en este documento.

Requisitos

Aplicación de Meta

Debes tener una aplicación empresarial de Meta que pueda usar la API de nube y la API de administración de WhatsApp Business con los datos de los clientes incorporados y que pueda gestionar webhooks de la API de nube y la API de administración de WhatsApp Business. La aplicación también debe estar asociada a tu cuenta empresarial de Meta o haber sido reclamada por ella.

Si no dispones de una cuenta empresarial de Meta, o si tienes una pero no has configurado el producto de WhatsApp, deberás completar los pasos descritos en nuestra guía Introducción de la API de nube. Al completar estos pasos, se generarán todos los activos necesarios para probar la API de nube y la API de administración de WhatsApp Business.

Revisión de la aplicación

Tu aplicación de Meta debe someterse al proceso de revisión de la aplicación y aprobarse (es decir, tener acceso avanzado) para los permisos whatsapp_business_messaging y whatsapp_business_management.

Prácticas recomendadas

Una vez te hayas asegurado de que tu aplicación puede hacer frente a todas las diferencias entre las API, recomendamos migrar primero un número de teléfono de empresa de bajo volumen y verificar que todas las funciones que pretendes ofrecer con la API de nube funcionan correctamente. Después de comprobar que todo funciona como debería, migra el resto de números.

También recomendamos llevar a cabo la migración cuando el tráfico a la implementación de tu API local sea bajo.

Diferencias entre las API

Las siguientes funciones de la API local no se admiten o se tratan de forma distinta en la API de nube. Comprueba que tu aplicación puede hacer frente a estas diferencias antes de comenzar el proceso de migración.

Webhooks

Las estructuras de carga útil de los webhooks de la API de nube y la API de administración de WhatsApp Business son diferentes de las de la API local. Recomendamos crear un extremo de webhooks nuevo que gestione exclusivamente la API de nube y la API de administración de WhatsApp Business.

Consulta los siguientes documentos para obtener más información sobre las diferencias de las cargas útiles y cómo configurar webhooks en la aplicación mediante el panel de aplicaciones:

Ten en cuenta que, después de migrar un número de teléfono de empresa a la API de nube, debes usar el extremo Cuenta de WhatsApp Business > Aplicaciones suscritas para suscribir tu aplicación de Meta a webhooks en la cuenta WABA asociada al número de teléfono de empresa:

Sintaxis de la solicitud

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

Una vez se haya completado la migración a la API de nube, ya no se entregarán los webhooks de la API local del número de teléfono de empresa y comenzará la entrega de webhooks de la API de nube.

Contenido multimedia

Los identificadores de contenido multimedia para el contenido multimedia subido a la API local no se pueden utilizar al enviar mensajes con la API de nube, por lo que deberás volver a subir el contenido multimedia con la API de nube para generar identificadores de contenido multimedia nuevos, o bien utilizar las URL de contenido multimedia si el contenido multimedia está alojado en un servidor público. Consulta Mensajes multimedia y Plantillas de mensajes basadas en contenido multimedia.

Ten en cuenta que, a fin de garantizar la integridad de los mensajes, algunos dominios de alojamiento de contenido multimedia que se admiten en la API local no se admiten en la API de nube. Si utilizas un servicio de alojamiento para el contenido multimedia, recomendamos probar las URL de contenido multimedia en mensajes de formato libre y plantillas de mensajes antes de llevar a cabo la migración. Si crees que tu host se ha bloqueado por error, contacta con el servicio de asistencia.

Códigos de error

Los códigos de error de la API de nube y la API de administración de WhatsApp Business son diferentes de los de la API local. Consulta los siguientes documentos:

Validación de propiedades

  • La API local puede aceptar propiedades desconocidas en las cargas útiles del cuerpo de las solicitudes POST de los mensajes, pero la API de nube rechazará tales solicitudes, por lo que tus solicitudes de envío de mensajes deberán utilizar únicamente propiedades admitidas.
  • La API local permite omitir los índices de botones al enviar mensajes con un único botón, pero la API de nube rechazará tales solicitudes, por lo que tus solicitudes de envío de mensajes que incluyan botones también deberán incluir los índices y sus valores correspondientes.
  • La API local acepta cadenas de texto con espacios iniciales o finales (o que solo contienen espacios) en las propiedades del objeto de acción y botón al enviar mensajes interactivos, pero la API de nube rechazará tales solicitudes.

Mensajes de pulsar para hablar

La API local identifica los mensajes de pulsar para hablar (PTT) en los webhooks estableciendo el valor de messages.type en voice, mientras que la API de nube lo hace estableciendo el valor de messages.audio.voice en true.

Paquetes de stickers

La API de nube no admite los paquetes de stickers.

Tiempo de inactividad

El tiempo de inactividad comienza al realizar el paso final de la migración (registro del número de teléfono para su uso con la API de nube) y dura unos pocos segundos. Durante este periodo, los mensajes que los usuarios de WhatsApp envíen al número de teléfono se anularán de forma silenciosa.

A fin de minimizar el impacto del tiempo de inactividad, te recomendamos programar la migración durante un periodo de baja actividad del número de teléfono.

Rendimiento

Si el número de teléfono de empresa local tiene varias conexiones que ejecutan dos o más particiones, se actualizará automáticamente a un rendimiento alto en la API de nube.

Cuentas empresariales oficiales

Si migras un número de teléfono de empresa que tiene un estado de cuenta empresarial oficial (OBA), dicho estado se conservará si incluyes sus metadatos (generados en el paso 2) al registrar el número (paso 3). Si se omiten estos datos, el número perderá su estado de OBA.

Asistencia para la migración

Si tienes dudas o necesitas ayuda con la migración, crea un ticket de Asistencia directa con la siguiente información:

  • Tema: WhatsApp Business: API de nube
  • Tipo de solicitud: Problemas con la migración API local -> API de nube

Paso 1: desactivar la verificación en dos pasos

Si conoces el PIN del número de teléfono de empresa, puedes omitir este paso.

Necesitarás el PIN del número de teléfono de empresa para el paso 3, por lo que, en caso de no saber cuál es, primero deberás desactivar la verificación en dos pasos en el número de teléfono de empresa. Si no eres el propietario del número de teléfono de empresa, pide al propietario que la desactive.

Paso 2: Generar los metadatos del número de teléfono

Utiliza la API de copia de seguridad y restauración para generar los metadatos del número de teléfono de empresa.

Sintaxis de la solicitud

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

El valor de <PASSWORD> puede ser cualquier cadena. Este valor se utilizará para cifrar los metadatos, así que guárdalo para el paso siguiente.

Respuesta

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

La API devolverá una cadena cifrada asignada a la propiedad data que describe el número de teléfono de empresa y su configuración. Guarda este valor, ya que lo necesitarás en el siguiente paso.

  • <METADATA>: cadena cifrada que describe el número de teléfono de empresa y su configuración. Guarda este valor, ya que lo necesitarás en el siguiente paso.
  • <API_STATUS>: estado de implementación de la API local.
  • <API_VERSION>: número de la versión de la API local que estás utilizando.

Ejemplo de solicitud

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Ejemplo de respuesta

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Paso 3: Registrar el número

No se necesita una contraseña de un solo uso (OTP) si los metadatos de la copia de seguridad del paso 2 anterior se han pasado correctamente y sin ninguna modificación a la API de nube en el paso 3 (este paso).

Utiliza el extremo Número de teléfono de WhatsApp Business > Registrar de la API de nube para registrar el número para su uso con la API de nube.

Incluye el valor de los metadatos del número de teléfono de empresa cifrado y la contraseña del paso anterior. Aunque es posible registrar el número de teléfono sin estos datos, los datos del perfil del número de teléfono de empresa se perderán si no se incluyen, lo que puede afectar al estado de cuenta de empresa oficial de la cuenta de WhatsApp Business.

Sintaxis de la solicitud

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Cuerpo de la solicitud POST

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}
  • <NEW_OR_EXISTING_PIN: PIN actual o PIN que quieres establecer en el número de teléfono de empresa.
  • <PASSWORD: contraseña que has utilizado para generar los metadatos del número de teléfono de empresa en el paso anterior.
  • <METADATA: cadena cifrada generada en el paso anterior que describe el número de teléfono de empresa y su configuración.

Respuesta

{
  "success": <SUCCESS>
}

La API responderá con el valor de success establecido en true si el registro se realiza correctamente, o en false si se ha producido un error.

Ejemplo de solicitud

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Ejemplo de respuesta

{
  "success": true
}

Paso 4: Comprobar el estado de los mensajes (opcional)

Solicita el campo health_status para el número de teléfono de empresa y comprueba que se puede utilizar para intercambiar mensajes con la API de nube. Consulta Estado de los mensajes.