API de la nube

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

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

La API de instalaciones locales dejará de estar disponible. Consulta nuestro documento Fin de la API de instalaciones locales para conocer los detalles y descubrir cómo migrar a nuestra nueva generación de API de la nube.

En este documento, se explica cómo migrar números de teléfono de empresas de la API de la nube a la API de instalaciones locales. Para hacer realizar migraciones de la API de instalaciones locales a la API de la nube, consulta Migrar de instalaciones locales a la nube.

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

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;
  • 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 facilitar la migración, debes conocer todas las diferencias que existen entre las API y tomar las medidas adecuadas para abordarlas antes de realizar los pasos migratorios descritos en este documento.

Prácticas recomendadas

Después de asegurarte de que tu app pueda manejar todas las diferencias de 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 instalaciones locales 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

Asegúrate de que tu app pueda dar respuesta a estas diferencias antes de comenzar el proceso de migración.

Webhooks

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

Consulta los siguientes documentos para entender las diferencias de la carga útil:

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

Contenido multimedia

Los identificadores de contenido multimedia de cualquier contenido subido a la API de la nube no se pueden usar cuando se envían mensajes con la API de instalaciones locales. Por lo tanto, debes volver a subir contenido multimedia usando la API de instalaciones locales para generar nuevos identificadores de contenido multimedia o usar URL de contenido multimedia si el medio está alojado en un servidor público. Consulta Enviar mensajes multimedia.

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 en locales. Consulta los siguientes documentos:

Mensajes de presionar para hablar

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

Tiempo de inactividad

El tiempo de inactividad comienza tan pronto como se realiza el paso de registro (paso 3) y sólo debería durar unos segundos. Durante este tiempo, los mensajes que envían los usuarios de WhatsApp se descartarán de forma silenciosa.

Te recomendamos mucho programar la migración para un momento en que el número experimente baja actividad, para minimizar cualquier impacto del tiempo de inactividad.

Paso 1: Integra la API de instalaciones locales

Como te dispones a migrar un número de teléfono de la empresa a la API de instalaciones locales, asegúrate de que tu app pueda usar correctamente la API de la nube y que la cuenta de WhatsApp Business asociada con el número de teléfono de la empresa tenga configurados correctamente los webhooks.

Paso 2: Prepara la migración

Te sugerimos que dejes de enviar mensajes mientras completas la migración.

El cliente de la API de instalaciones locales de WhatsApp Business debe cumplir determinados requisitos de red para poder comunicarse con los servidores de WhatsApp. Para asegurarte de que todo está listo, consulta Configura y depura tu red.

Paso 3: Registra el cliente de la API

Registra el número de teléfono de la empresa en el cliente de la API de instalaciones locales. Para hacerlo, haz una llamada al punto de conexión /account:

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Según la respuesta que se reciba, es posible que el procedimiento de registro se considere finalizado o que se requiera otro paso para finalizarlo. Si la operación se realiza correctamente, recibirás uno de los siguientes códigos de estado HTTP. Sigue las instrucciones que correspondan según la respuesta que recibas:

  • 201 Created: La cuenta ya existe. Ya estás registrado, por lo que no necesitas hacer nada más.
  • 202 Accepted: La cuenta no existe. Según el método que hayas seleccionado en la solicitud, consulta tus SMS o tu número de voz para obtener el código de registro. En la respuesta, se incluirá la carga devuelta, que tendrá el vname decodificado a partir del parámetro cert para que confirmes que se configure el nombre para mostrar correcto. Si es correcto, ve a Completar el registro de tu cuenta para completar el registro.

Consulta todos los campos disponibles relacionados con este punto de conexión aquí.

Una vez completado el registro, el cliente de la API de instalaciones locales será el que reciba los mensajes.

Paso 4: Configura fragmentos

Una vez que esté registrado el cliente, puedes configurar fragmentos, si es necesario.

Paso 5: Comienza a enviar mensajes

Todo está listo para enviar mensajes a tus clientes. Consulta las guías sobre Envío de mensajes para obtener asesoramiento.