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

Migrar de la API de instalaciones locales a la API de la nube

En este documento, se explica cómo migrar números de teléfono del negocio desde la API de instalaciones locales a la API de la nube.

Ten en cuenta que migrar un número de teléfono de una API a otra no es lo mismo que migrar un número de una cuenta de WhatsApp Business (WABA) a otra.

Para realizar una migración de la API de la nube a la API de instalaciones locales, consulta Migrar de la API de la nube a la API de instalaciones locales.

Cómo funciona

El proceso de migración implica generar metadatos sobre el número de teléfono del negocio y, luego, usar esos datos para registrar el número a fin de usarlo con la API de la nube. A su vez, esto anula el registro del número de la API de instalaciones locales, ya que solo se puede registrar un número a la vez para usarlo con una API.

La migración NO afecta lo siguiente:

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

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

Requisitos

App de Meta

Debes tener una app de Meta Business que sea capaz de usar la API de la nube y la API del administrador comercial con datos de clientes incorporados, y de procesar los webhooks de la API de la nube y la API del administrador comercial. La app también debe estar asociada a tu cuenta comercial de Meta verificada, o bien dicha cuenta debe haber reclamado la app.

Si no tienes una app de negocios de Meta o si tienes una, pero no configuraste el producto de WhatsApp en ella, sigue los pasos de la guía de primeros pasos de la API de la nube. Al completar estos pasos, se generarán todos los recursos necesarios para probar la API de la nube y la API del administrador comercial.

Revisión de apps

Tu app de Meta debe someterse a revisión y recibir la aprobación (es decir, tener acceso avanzado) en relación con los permisos whatsapp_business_messaging y whatsapp_management.

Prácticas recomendadas

Después de asegurarte de que tu app pueda manejar todas las diferencias entre las API, te recomendamos primero migrar un número de teléfono de empresa de bajo volumen y verificar que toda la funcionalidad que deseas ofrecer con la API de la nube funcione correctamente. Después de verificar que todo funciona correctamente, migra más números.

También te recomendamos que realices la migración cuando el tráfico a tu API de instalaciones locales sea reducido.

Diferencias entre las API

Las siguientes funciones de la API de instalaciones locales no son compatibles con la API de la nube o reciben un tratamiento diferente por parte de ella. Asegúrate de que tu app pueda manejar estas diferencias antes de comenzar el proceso de migración.

Webhooks

Las estructuras de la carga útil de los webhooks de la API de la nube y la API del administrador comercial son diferentes de las estructuras de la carga útil de la API de instalaciones locales. Te recomendamos crear un nuevo punto de conexión de webhooks que pueda gestionar exclusivamente la API de la nube y la API del administrador comercial.

Consulta los siguientes documentos para entender las diferencias entre las cargas útiles y cómo configurar webhooks en tu app a través del panel de apps:

Configuración: webhooks para WhatsApp
Cargas útiles de webhooks de la API de la nube: referencia de cargas útiles de notificaciones mediante webhooks
Cargas útiles de webhooks de la API del administrador comercial: configuración de webhooks

Ten en cuenta que después de migrar un número de teléfono del negocio a la API de la nube, debes usar el punto de conexión Cuenta de WhatsApp Business > Apps suscritas para suscribir tu app de Meta a los webhooks de la WABA asociada al número del negocio:

Sintaxis de la solicitud

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

Una vez que se haya completado la migración a la API de la nube, se dejarán de entregar los webhooks de la API de instalaciones locales del número de teléfono del negocio. A partir de ese momento, comenzará la entrega de los webhooks de la API de la nube.

Contenido multimedia

No pueden usarse los identificadores de contenido multimedia de cualquier contenido subido a la API de instalaciones locales cuando se envían mensajes mediante la API de la nube. Por ello, debes volver a subir contenido multimedia usando la API de la nube con el fin de generar nuevos identificadores de contenido multimedia o de usar URL de contenido multimedia, si este contenido está alojado en un servidor público. Consulta Mensajes de contenido multimedia y Plantillas de mensajes basadas en contenido multimedia.

Ten en cuenta que, para garantizar la integridad de los mensajes, algunos dominios de alojamiento de contenido multimedia que permite la API de instalaciones locales no los permite la API de la nube. Si usas un servicio de alojamiento para tu contenido multimedia, te recomendamos probar las URL de contenido multimedia en mensajes sin formato y mensajes de plantilla antes de realizar la migración. Si crees que tu organizador está bloqueado por error, contacta al servicio de asistencia.

Códigos de error

Los códigos de error de la API de la nube y la API del administrador comercial son diferentes de los códigos de error de la API de instalaciones locales. Consulta los siguientes documentos:

Validación de propiedades

La API de instalaciones locales puede aceptar propiedades desconocidas en la carga útil del cuerpo de las solicitudes POST de mensajes, pero la API de la nube rechazará estas solicitudes. Por ello, en tus solicitudes de envío de mensajes, usa únicamente propiedades admitidas.
La API de instalaciones locales permite omitir los índices de los botones al enviar mensajes con un solo botón, pero la API de la nube rechazará estas solicitudes. Por eso, debes asegurarte de que tus solicitudes de envío de mensajes que incluyan botones también incluyan índices y sus valores.
La API de instalaciones locales acepta cadenas de texto que contienen espacios al principio o al final (o solo espacios) en las propiedades de objetos de acciones y botones al enviar mensajes interactivos, pero la API de la nube rechazará estas solicitudes.

Mensajes de presionar para hablar

La API de instalaciones locales identifica los mensajes de presionar para hablar (PTT) en los webhooks configurando messages.type en voice, pero la API de la nube identifica los mensajes PTT configurando messages.audio.voice en true.

Paquetes de stickers

La API de la nube no admite los paquetes de stickers.

Tiempo de inactividad

El tiempo de inactividad comienza a correr tan pronto como se realiza el paso final de migración (registrar el número para su uso con la API de la nube) y solo debería ser de unos segundos. Durante este tiempo, los mensajes enviados al número por usuarios de WhatsApp se descartarán de forma discreta.

Te recomendamos especialmente programar la migración para un momento en que el número experimente baja actividad. De esta manera, se puede minimizar cualquier impacto que pueda tener el tiempo de inactividad.

Rendimiento

Si hay dos o más fragmentos en ejecución en el número de teléfono comercial de instalaciones locales, este se actualizará automáticamente a alto volumen en la API de la nube.

Cuentas de empresas oficiales

Si estás migrando un número de teléfono de empresa que tiene un estado de cuenta de empresa oficial (OBA) , su estado se conservará si incluyes los metadatos (generados en el paso 2) al registrarlo (paso 3). Si omites estos datos, el número perderá su estatus de OBA.

Asistencia para la migración

Si tienes preguntas o necesitas ayuda con la migración, envía un ticket de asistencia directa que incluya:

Tema: WABiz: API de la nube
Tipo de solicitud: API de instalaciones locales -> Problemas de migración de la API de la nube

Paso 1: Desactiva la verificación en dos pasos

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

Necesitarás el PIN del número de teléfono del negocio al realizar el paso 3. Por tanto, si no lo conoces, primero debes desactivar la verificación en dos pasos en el número de teléfono del negocio. Si no tienes el número de teléfono del negocio, pide al propietario que la desactive.

Paso 2: Genera metadatos de números de teléfono

Utiliza la API de copia de seguridad y restauración para generar metadatos sobre el número de teléfono de tu negocio.

Sintaxis de la solicitud

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

<PASSWORD> puede ser cualquier cadena. Este valor se usará para codificar los metadatos. Tenlo presente, ya que lo necesitarás en el paso siguiente.

Respuesta

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

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

<METADATA>: se trata de la cadena codificada que describe el número de teléfono de tu negocio y su configuración. Captura este valor, ya que lo necesitarás en el siguiente paso.
<API_STATUS>: se refiere al estado de la implementación de la API de instalaciones locales.
<API_VERSION>: número de versión de la API de instalaciones locales que está en ejecución.

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: Registra 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 mencionado antes se envían correctamente y sin modificaciones a la API de la nube durante el Paso 3 (este paso).

Usa el punto de conexión Número de teléfono de WhatsApp Business > Registro de la API de la nube para registrar el número, a fin de usarlo con la API de la nube.

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

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 preexistente o PIN que quieres establecer en relación con el número de teléfono del negocio.
<PASSWORD: contraseña que usaste para generar los metadatos del número de teléfono de tu negocio en el paso anterior.
<METADATA: se trata de la cadena codificada que describe el número de teléfono de tu negocio y su configuración, que se generó en el paso anterior.

Respuesta

{
  "success": <SUCCESS>
}

La API responderá con success en true si el registro es correcto, o bien, en false si se produjo 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: Comprueba el estado general de los mensajes (opcional)

Solicita el campo health_status en el número de teléfono del negocio y verifica que se pueda usar para los mensajes que se cursan con la API de la nube. Consulta Estado general de los mensajes.

Plataforma de WhatsApp Business | API de la nube | API de administración de WhatsApp Business