API de nube

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

Migrar de la API de nube a la API local

Estamos retirando la API local. Consulta nuestro documento Retirada de la API local para obtener más información y aprender a migrar a nuestra API de nube de nueva generación.

En este documento, se describe cómo migrar números de teléfono de empresa de la API de nube a la API local. Para hacer la migración de la API local a la API de nube, consulta Migrar 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.

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.

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 local 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

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. Te recomendamos que crees un nuevo extremo de webhooks que pueda gestionar webhooks de la API local exclusivamente.

Consulta los siguientes documentos para ayudarte a comprender las diferencias de carga útil:

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

Contenido multimedia

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

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:

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.

Tiempo de inactividad

El tiempo de inactividad comienza al realizar el paso de registro (paso 3) y debería durar 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.

Paso 1: Integrar la API local

Como vas a migrar un número de teléfono de empresa a la API local, asegúrate de que la aplicación pueda usar correctamente el cliente de dicha API y que la cuenta de WhatsApp Business asociada al número de teléfono de empresa tenga configurados correctamente los webhooks.

Paso 2: Prepararse para la migración

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

El cliente local de la API de WhatsApp Business presenta determinados requisitos de red para conectarse a los servidores de WhatsApp. Para asegurarte de que tengas todo listo, consulta Configurar y depurar la red.

Paso 3: Registrar el cliente de la API

Registra el número de teléfono de empresa en el cliente de la API local. Para ello, llama al extremo /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
}

En función de la respuesta recibida, el procedimiento de registro se puede considerar finalizado o requerir otro paso para completarse. Si la operación se realiza correctamente, recibirás uno de los códigos de estado HTTP siguientes. Sigue las instrucciones correspondientes a la respuesta que has recibido:

  • 201 Created: la cuenta ya existe. Ya estás registrado, por lo que no tienes que hacer nada más.
  • 202 Accepted: la cuenta no existe. En función del método seleccionado en la solicitud, comprueba en el SMS o la llamada de voz el código de registro. Esta respuesta incluirá una carga devuelta con el elemento vname descodificado del parámetro cert para que confirmes que se está estableciendo el nombre para mostrar correcto. Si es correcto, dirígete a Finalización del registro de la cuenta para completar el registro.

Consulta todos los campos disponibles para este extremo aquí.

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

Paso 4: Definir las particiones

Cuando el cliente esté registrado, puedes definir las particiones, si es necesario.

Paso 5: Empezar a enviar mensajes

Ya tienes todo listo para empezar a enviar mensajes a tus clientes. Consulta las instrucciones en las guías Enviar mensajes.