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.
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 quedafailedconqr_timeouty 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. Sincountryse usa el país que detecta el navegador de tu cliente en la página y, si no detecta ninguno, Colombia (co). No vale condevice_id(una reconexión no crea el número) ni contype: "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_typeses 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: trueofrece además un número de EE. UU. del pool de Funnelchat: es siempre un número dedicado, así que exigededicatedenallowed_connection_typesy no vale condevice_id; si no, responde422 invalid_request. Si falla el inicio de sesión de Facebook (facebook_auth_failed) o Meta da un error (meta_error), el link siguependingy tu cliente puede intentarlo de nuevo con el mismo link; al quinto intento fallido el link pasa afailedcon ese código. Mientras el alta oficial por link no esté habilitada responde503 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.
httpAuthorizationBearer <clave>application/json- body
Body of POST connect-links. A validation failure answers 422 invalid_request
({error, message, errors}).
type*stringmeta: official number (Embedded Signup of Meta). qr: number by QR code.
"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).
1 <= items <= 2provision_us_number?booleantype: 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.
^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.
^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).
^[A-Za-z]{2}$external_reference?|Your own reference; it is copied to the number the link creates.
length <= 255return_url?|Where to send the customer at the end (https only). It receives only the result.
urilength <= 2048expires_in_minutes?|How long the link lives, in minutes.
30 <= value <= 10080El link creado. url aparece solo en esta respuesta.
application/json- 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" }}Números
Conectar un número de WhatsApp a tu cuenta y ver, editar, reiniciar, desconectar y borrar los tuyos; sus links de alta, su QR, su nombre de usuario, su historial de conexión y la salud de uno oficial.
Ver tus números GET
Sirve para listar tus números de WhatsApp con su proveedor, si están conectados y activos y su estado de salud, y obtener los IDs que usan las demás operaciones.