Referencia (endpoints)Números

Conectar un número

Sirve para conectar un número de WhatsApp a tu cuenta —el tuyo o el de tu cliente— desde una página de Funnelchat, sin entrar al panel: le das la url de un solo uso a quien lo va a conectar y te enteras del resultado por webhook o en tu URL de vuelta.

POST
/connect-links

Escritura · requiere Números de WhatsApp → Crear, conectar y borrar.

🔑 Da el control de un WhatsApp. Por eso pide Números de WhatsApp → Crear, conectar y borrar: crear un número ocupa un lugar del plan, y quien escanee su QR o use un link de alta conecta un teléfono a esta cuenta. Trata el QR y la URL del link como un secreto.

Un link de un solo uso para que tu cliente conecte un número de WhatsApp a tu cuenta, desde una página de Funnelchat y sin entrar al panel. Envíale la url de la respuesta: es la única vez que aparece (Funnelchat guarda solo un hash) y quien la tenga puede conectar un número a tu cuenta mientras el link esté pendiente. Trátala como un secreto.

Abrir la página no usa el link (la vista previa de un mensajero no lo gasta): el link se usa cuando tu cliente toca el botón para conectar.

  • type: "qr": al tocar el botón se crea el número (si no es una reconexión) y la página muestra el QR, que renueva sola cada 5 segundos. Tu cliente tiene 10 minutos desde que toca el botón para escanearlo; si no lo escanea a tiempo, el link queda failed con qr_timeout y el número que creó el link se borra (libera el lugar). Si el alta tomó un lugar libre que tu cuenta ya tenía, ese lugar no se borra: queda como estaba. country (opcional, ISO 3166-1 alfa-2, por ejemplo "mx") es el país desde donde se abre la sesión de WhatsApp del número: conviene que sea el del teléfono de tu cliente, porque WhatsApp puede rechazar la vinculación («no se puede vincular ahora») si la sesión se abre desde otro país. Sin country se usa el país que detecta el navegador de tu cliente en la página y, si no detecta ninguno, Colombia (co). No vale con device_id (una reconexión no crea el número) ni con type: "meta".
  • type: "meta": número oficial con el Embedded Signup de Meta, el mismo del panel. El número se crea al terminar el Embedded Signup. allowed_connection_types es obligatorio: coexistence (el número sigue en la app WhatsApp Business), dedicated (un número solo para la API) o los dos, y entonces elige tu cliente. provision_us_number: true ofrece además un número de EE. UU. del pool de Funnelchat: es siempre un número dedicado, así que exige dedicated en allowed_connection_types y no vale con device_id; si no, responde 422 invalid_request. Si falla el inicio de sesión de Facebook (facebook_auth_failed) o Meta da un error (meta_error), el link sigue pending y tu cliente puede intentarlo de nuevo con el mismo link; al quinto intento fallido el link pasa a failed con ese código. Mientras el alta oficial por link no esté habilitada responde 503 meta_connect_disabled. El cliente le paga a Meta los mensajes con el medio de pago de su cuenta de WhatsApp Business: tiene que cargarlo en Meta.

El cupo del plan y el pago de la cuenta se controlan al crear el link y otra vez al usarlo: el link no reserva lugar. Con el pago vencido, crear el link responde 403, y usarlo deja el link failed con quota_exceeded. Con device_id el link reconecta ese número (no ocupa un lugar nuevo; el type tiene que coincidir con el del número) y revoca los links de reconexión anteriores de ese número. Cada workspace puede tener como máximo 20 links pendientes.

Para enterarte del resultado: el webhook device.connected (trae connect_link_id y external_reference), la return_url o GET connect-links/{link}. Al terminar, la página lleva a tu cliente a la return_url con el resultado en la query string, nada más: connect_link_id, status (completed o failed), device_id (solo si completó) y error_code (solo si falló); por ejemplo https://tu-sistema.com/vuelta?connect_link_id=<id del link>&status=completed&device_id=<id del número>. Si tu return_url ya trae parámetros, se suman a los tuyos. El link muere si revocas la clave de API que lo creó.

Acepta el header Idempotency-Key (de 1 a 255 caracteres) para reintentar sin crear otro link: la misma clave con el mismo cuerpo, desde el mismo workspace y dentro de las 24 horas, devuelve el mismo link. Otro workspace de la cuenta puede usar la misma clave sin cruzarse con este.

Autorización

http
headerAuthorizationBearer <clave>

Cuerpo del pedido

application/json
  1. body

Body of POST connect-links. A validation failure answers 422 invalid_request ({error, message, errors}).

type*string

meta: official number (Embedded Signup of Meta). qr: number by QR code.

Valor en"meta""qr"
allowed_connection_types?array<>

type: meta only, and required there: which official connections the customer may choose (coexistence keeps the WhatsApp Business app; dedicated does not).

Elementos1 <= items <= 2
provision_us_number?boolean

type: meta only: offer a US number of the Funnelchat pool.

device_id?|

Reconnect THIS number of the account instead of adding one (uses no new place). Id opaco: un texto que empieza con dev_. Se usa tal como llega; no se arma ni se interpreta.

Patrón^dev_[A-Za-z0-9]{23}$
same_number_as?|

type: qr only: add QR to this coexistence number of the account. Id opaco: un texto que empieza con dev_. Se usa tal como llega; no se arma ni se interpreta.

Patrón^dev_[A-Za-z0-9]{23}$
country?|

type: qr only, and not with device_id (a reconnection creates nothing): country the WhatsApp session is opened from (ISO 3166-1 alpha-2, two letters, any case).

Patrón^[A-Za-z]{2}$
external_reference?|

Your own reference; it is copied to the number the link creates.

Largolength <= 255
return_url?|

Where to send the customer at the end (https only). It receives only the result.

Formatouri
Largolength <= 2048
expires_in_minutes?|

How long the link lives, in minutes.

Rango30 <= value <= 10080

Cuerpo de la respuesta

El link creado. url aparece solo en esta respuesta.

application/json
  1. response
data*
curl -X POST "https://example.com/connect-links" \  -H "Content-Type: application/json" \  -d '{    "type": "meta"  }'
{  "data": {    "id": "lnk_A2GK1NzySI7ig9NzsrC1gOu",    "type": "string",    "status": "string",    "url": "string",    "expires_at": "string",    "allowed_connection_types": [      "string"    ],    "provision_us_number": true,    "country": "string",    "device_id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX",    "external_reference": "string",    "return_url": "string",    "error_code": "string",    "created_at": "string",    "completed_at": "string"  }}

Esto es lo que se copia para tu IA

Cargando…