Referencia (endpoints)Números

Crear un número para conectar por QR

Sirve para sumar a tu cuenta, desde tu sistema y sin entrar al panel, un número que se conecta escaneando un código QR. Ocupa un lugar del plan; después pide su código con Ver el QR de un número.

POST
/devices

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.

Crea un número de la cuenta que se conecta escaneando un código QR con la app de WhatsApp (connection: "qr"). Después pide su QR con GET devices/{device}/qr, o envíale a tu cliente un link de alta (POST connect-links con type: "qr"). El proveedor lo elige Funnelchat, igual que en el panel.

Ocupa un lugar del plan, como «Agregar número» en el panel. Con same_number_as (un número de la cuenta conectado a la API oficial en coexistencia) suma QR a ese mismo número y no ocupa un lugar nuevo.

Un número conectado por QR no es oficial: WhatsApp puede restringirlo o bloquearlo si envía mensajes que la gente no espera. Para volumen, usa un número oficial (un link de alta con type: "meta").

country es el país desde donde se abre la sesión de WhatsApp del número (ISO 3166-1 alfa-2, por ejemplo "mx"). Conviene que sea el del teléfono que va a escanear el QR: 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 Colombia (co): la llamada llega por el borde de la API y su ubicación no es la de tu cliente, así que no sirve para elegirlo. Si Funnelchat no tiene salida en ese país, usa la más cercana.

El workspace tiene como máximo un número por QR que nunca se conectó (si la cuenta no usa workspaces, la cuenta entera): mientras exista, responde 409 pending_number_exists con su device_id (conéctalo o bórralo).

Con el header Idempotency-Key puedes reintentar sin duplicar: la misma clave con el mismo cuerpo, desde el mismo workspace y dentro de las 24 horas, devuelve el mismo número (Idempotent-Replayed: true). Otro workspace de la cuenta puede usar la misma clave sin cruzarse con este. La misma clave con otro cuerpo responde 422 idempotency_key_mismatch; mientras la primera sigue en curso, 409 operation_in_progress. Una clave vacía o de más de 255 caracteres responde 422 invalid_idempotency_key y no crea nada.

Autorización

http
headerAuthorizationBearer <clave>

Cuerpo del pedido

application/json
  1. body

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

connection*"qr"

How the number connects. Only qr today: an official (Meta) number is created by a connect link (POST connect-links with type: meta).

Valor en"qr"
alias?|

Name shown in the panel.

Largolength <= 255
external_reference?|

Your own reference for this number (for example, your customer's id). Not unique.

Largolength <= 255
same_number_as?|

Id of a number of the account that is connected to the official API in coexistence: the new QR connection is the SAME number (it does not use a new place of the plan). 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?|

Country the WhatsApp session is opened from (ISO 3166-1 alpha-2, two letters, any case): send the country of the phone that will scan the QR. Without it, the default.

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

Cuerpo de la respuesta

application/json
  1. response
data*
curl -X POST "https://example.com/devices" \  -H "Content-Type: application/json" \  -d '{    "connection": "qr"  }'
{  "data": {    "id": "dev_Ac7Ku7iIZDXJTjdCu0UB1mX",    "alias": "string",    "image": "string",    "color": "string",    "number": "string",    "normalized_number": "string",    "first_conecction_at": "string",    "user_id": "usr_AdaVCroxOubVJxQ0exvtano",    "provider": 1,    "waba_id": "string",    "phone_number_id": "string",    "whatsapp_username": "string",    "is_business": 0,    "connected": 0,    "active": 0,    "health": "string",    "number_key": "string",    "number_key_confirmed": "string",    "is_coexistence": true,    "slot_state": "string",    "pool_suspended": true,    "pool_suspension_reason": "string",    "pool_keep": true,    "qr_allowed": true,    "can_change_to_meta": true,    "connected_by_user_id": "usr_AdaVCroxOubVJxQ0exvtano",    "connected_by_name": "string",    "abilities": {      "connect": true,      "disconnect": true,      "delete": true,      "update": true    },    "capabilities": {      "messages": {        "text": true,        "media": true,        "buttons": true,        "lists": true,        "templates": true,        "location": true,        "voice_note": true,        "polls": true,        "events": true,        "contact_card": true,        "reactions": true      },      "groups": {        "create": true,        "add_participants": true,        "remove_participants": true,        "admins": true,        "photo": true,        "settings": true,        "invite_link": true,        "send": true,        "join_requests": true      },      "statuses": [        "string"      ]    },    "connection": "qr",    "external_reference": "string",    "overloaded": true,    "overloaded_computed_at": "2019-08-24T14:15:22Z",    "overloaded_groups_count": 0,    "overloaded_one_to_one_count": 0,    "overloaded_has_pending_broadcast": true,    "overloaded_has_active_flow": true,    "overloaded_has_active_ai_agent": true,    "overloaded_alert_level": "string",    "overloaded_dismissed_at": "2019-08-24T14:15:22Z",    "sync_all_groups": true  }}

Esto es lo que se copia para tu IA

Cargando…