Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Cómo permitir que tus usuarios conecten cuentas de WhatsApp, Instagram y TikTok a tu app

Para permitir que tus usuarios conecten cuentas de WhatsApp, Instagram y TikTok a tu app, crea una sesión de conexión con la Partner API de easyCoexistence y envía al usuario a su url alojada. Allí conectan un número de WhatsApp mediante el Embedded Signup de Meta o inician sesión en Instagram, Facebook, TikTok, YouTube, LinkedIn y más canales, y luego regresan a tu redirect_url con el nuevo id de conexión o de canal. Los enlaces duran una hora.

1 hour

Cuánto tiempo funciona un enlace de conexión; después, la sesión aparece como expirada y hace falta una nueva.

50 open

Sesiones de conexión que una cuenta puede tener abiertas a la vez, junto con un límite de 100 sesiones nuevas por hora.

5 statuses

Una sesión se crea, se abre, se conecta, se cancela o expira, según informa GET /connect-sessions/:id.

200 characters

La URL de callback alternativa más larga que Meta acepta para enviar a otro destino los webhooks de mensajes de un número de WhatsApp.

¿Cómo funciona un enlace de conexión?

Como una página de pago. Tu backend crea una sesión, tu interfaz envía al cliente a su url, el cliente conecta en una página de easycoexistence.com y el navegador vuelve a tu redirect_url. Luego tu backend confirma el resultado y obtiene las credenciales de la nueva conexión, todo con tu clave de API.

1CreatePOST /connect-sessions from your backend
2SendA redirect or a new tab to the session's url
3ConnectMeta's Embedded Signup, or the network's own sign-in
4ReturnYour redirect_url, with the session, status and new id
5ConfirmGET /connect-sessions/:id, then the credentials

¿Qué incluye la petición?

Un cuerpo JSON enviado por POST a https://easycoexistence.com/api/v1/connect-sessions, con tu clave de API como token Bearer. Solo redirect_url es obligatorio:

  • redirect_url: una URL https a la que llega el cliente después.
  • channel: whatsapp, el valor por defecto, o una red social abierta para tu cuenta, por su nombre en minúsculas, como instagram, tiktok o youtube.
  • external_ref: tu propio id para este cliente, de hasta 200 caracteres.
  • partner_name: el nombre que muestra la página alojada, de hasta 80 caracteres; por defecto, el nombre de tu cuenta.
  • webhook_url con webhook_verify_token: solo para números, y siempre juntos. Meta entrega allí los mensajes del número desde el momento en que se conecta.
Create a session for a WhatsApp number
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
  -H "Authorization: Bearer $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "redirect_url": "https://app.example.com/connect/return",
    "external_ref": "customer_4821",
    "partner_name": "ClinicApp",
    "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
    "webhook_verify_token": "another-long-random-string"
  }'

¿Qué se devuelve?

Un 201 con la sesión. Envía al cliente a url y guarda el id, que empieza por cs_, para consultar la sesión más tarde. expires_at vence una hora después de la creación, y connection_id o channel_id se completa cuando el cliente conecta, según el canal de la sesión. GET /connect-sessions/:id devuelve la misma estructura en cualquier momento.

201 Created
{
  "id": "cs_…",
  "url": "https://easycoexistence.com/connect/cs_…",
  "channel": "whatsapp",
  "status": "created",
  "external_ref": "customer_4821",
  "connection_id": null,
  "channel_id": null,
  "token_ready": false,
  "redirect_url": "https://app.example.com/connect/return",
  "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
  "last_error": null,
  "expires_at": "2026-10-31T15:00:00.000Z",
  "opened_at": null,
  "finished_at": null,
  "created_at": "2026-10-31T14:00:00.000Z"
}

¿Qué errores puede devolver la creación de una sesión?

Cada error tiene el mismo cuerpo, un objeto con un code y un message, y el message indica qué corregir. Crear una sesión puede devolver:

  • 400 invalid_json o invalid_request: el cuerpo no es un objeto JSON, o un campo no pasó la validación, como una redirect_url que no es https.
  • 400 channel_unavailable: el canal no está abierto para esta cuenta; el message enumera los que sí lo están.
  • 401 unauthorized: falta la clave de API o no es válida.
  • 402 billing_required: la cuenta aún no tiene tarjeta, y todo lo conectado a través de ella se factura a esa cuenta.
  • 429 cap_reached: ya hay 50 sesiones abiertas; espera a que terminen o expiren algunas.
  • 429 rate_limited: más de 100 sesiones en esta hora; el message indica cuánto esperar.

¿A dónde llega el cliente después?

A tu redirect_url, con el resultado añadido a su query string. El mismo resultado está en la sesión, que tu backend lee con GET /connect-sessions/:id:

  • session: el id de la sesión, cs_ seguido de caracteres aleatorios.
  • status: connected, o cancelled cuando el cliente eligió Cancel and go back.
  • external_ref: tu id del cliente, cuando la sesión lo incluía.
  • connection_id: el id del nuevo número, para /connections.
  • channel_id: el id de la nueva cuenta social, para /channels.
A number connected
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…

¿Qué estados puede tener una sesión?

Cinco. GET /connect-sessions/:id informa el actual, con opened_at, finished_at y last_error, que indica por qué falló el último intento:

  • created: creada por tu backend, aún no abierta.
  • opened: el cliente cargó la página alojada.
  • connected: se conectó un número o una cuenta social, y su id figura en la sesión.
  • cancelled: el cliente salió con Cancel and go back.
  • expired: la hora se agotó antes de que la sesión terminara.

¿Cuánto tiempo funciona un enlace?

Una hora desde su creación. Después, la página alojada le indica al cliente que el enlace expiró, con un botón de vuelta a tu redirect_url marcado como status=cancelled, y la sesión aparece como expired. Una cuenta puede tener 50 sesiones abiertas y crear 100 por hora, porque Meta cuenta cada alta inicial contra un límite de la app que comparten todas las cuentas.

¿Qué hace external_ref?

Vincula cada conexión con tu cliente. El valor que envías se guarda en el número o canal que crea la sesión, se añade a la redirección y se incluye en cada evento de estado sobre él, de modo que GET /connections?external_ref=customer_4821 y GET /channels?external_ref=customer_4821 enumeran lo que ese cliente ha conectado. Un inicio de sesión con Facebook o LinkedIn puede traer varias Páginas a la vez: la redirección nombra la primera, y el filtro lista las demás. Usa un id estable de tu propia base de datos, no un correo que pueda cambiar.

¿Qué pasa si el cliente cancela o falla un inicio de sesión?

Depende de dónde ocurra, y la sesión guarda el registro:

  • La ventana emergente de Meta falla o se cierra: el cliente pulsa Connect de nuevo en la misma página mientras el enlace esté abierto.
  • Un inicio de sesión social se cancela o se rechaza: el cliente vuelve a la página alojada con el motivo y puede intentarlo otra vez hasta que el enlace expire.
  • La cuenta ya está conectada a través de otra cuenta de easyCoexistence: last_error lo indica, y el cliente inicia sesión con otra.
  • El cliente elige Cancel and go back: tu redirect_url recibe status=cancelled y la sesión se cierra, así que crea una nueva para otro intento.
  • El enlace expiró: crea una sesión nueva.

¿Qué pasa si un número se conecta sin el token del cliente?

A veces Meta termina el Embedded Signup sin emitir el token de negocio propio del cliente. La página alojada entonces pide una pasada más, que tarda unos segundos. Si el cliente la omite, la sesión aparece como connected con token_ready false y tu URL de eventos recibe connection.token_missing: el número recibe mensajes, ya que sus ids son válidos, pero no puede enviar hasta que una nueva sesión de conexión lo reconecte y emita el token.

¿Qué pasa si webhook_url no supera la verificación de Meta?

El número se conecta igualmente. Meta verifica una webhook_url con un handshake GET, que tu endpoint supera devolviendo hub.challenge cuando hub.verify_token coincide. Si falla, last_error de la sesión empieza con webhook_url was not applied y da el motivo de Meta, y PUT /connections/:id/webhook fija el destino una vez que el endpoint responde. Configurado dentro de las 24 horas posteriores a la conexión, sigue recibiendo la importación única de contactos y, si el cliente aceptó compartirlo, el historial de chats.

¿Qué ve el cliente?

Una página en easycoexistence.com con tu nombre tomado de partner_name, y sin cuenta, correo ni tarjeta que completar. Para un número de WhatsApp muestra una breve lista de elegibilidad, luego la ventana emergente de Meta y un código QR para escanear con la app de WhatsApp Business. Para una cuenta social muestra un solo botón, como Continue with TikTok, que abre la pantalla de consentimiento de la propia red en la misma pestaña, así que funciona también en teléfonos.

Errores comunes

  • Confiar solo en la query string. Cualquiera puede escribir status=connected en una URL, así que confirma con GET /connect-sessions/:id desde tu backend antes de marcar al cliente como conectado.
  • Incrustar el enlace en un iframe. Envía al cliente con una redirección o en una pestaña nueva, que es como están pensadas la página alojada y los inicios de sesión que abre.
  • Crear enlaces por adelantado. Cada uno funciona una hora y todas las sesiones abiertas cuentan para el límite de 50, así que crea la sesión cuando el cliente está a punto de conectar.
  • Enviar una webhook_url de más de 200 caracteres. Meta acepta URL de callback alternativas de hasta 200 caracteres, así que una más larga no se aplica y el número se conecta sin ella.
Hacerlo con EasyCoexistence

easyCoexistence conecta los números de WhatsApp de tus clientes y sus cuentas de Instagram, Facebook, TikTok, YouTube y LinkedIn, además de más canales, con tu software mediante un único enlace alojado, y luego entrega a tu backend las credenciales de cada conexión, los webhooks y los eventos de estado firmados. De US$ 9 a US$ 0.75 por conexión al mes, con un precio que baja a medida que añades conexiones, y los primeros 3 días gratis.

Preguntas frecuentes

¿Se puede usar un enlace de conexión dos veces?

No. Un enlace termina con un número, o con un inicio de sesión social, que en Facebook o LinkedIn puede traer varias Páginas. Después aparece como connected, así que crea una sesión nueva para la siguiente conexión.

¿Puedo enviar el enlace por correo o chat?

Sí, siempre que el cliente lo abra dentro de la hora. El id de sesión en la URL es lo que autoriza la página, así que envía cada enlace solo al cliente para el que se creó.

¿La página alojada funciona en teléfonos?

Los inicios de sesión sociales sí, ya que se abren en la misma pestaña. Un número de WhatsApp se conecta mejor desde un ordenador: en un teléfono la ventana emergente de Meta se abre como pestaña nueva, y hace falta el propio teléfono para escanear el código QR.

¿Cómo sé que un cliente se conectó sin consultar?

Configura una URL de eventos de estado en el panel, en Profile, Developers. easyCoexistence entonces envía connection.connected o channel.connected, firmados y con tu external_ref, en cuanto se completa la conexión.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el