developers
EN Crear cuenta

Empezar

Obtén un número de WhatsApp

Si no tienes un número para la Cloud API, usa uno de heysteff. Es un número de Estados Unidos (+1) que heysteff ya verificó en Meta: al conectar WhatsApp lo eliges en la ventana de Meta y queda en tu cuenta de WhatsApp Business. No recibes SMS ni llamadas en ningún teléfono tuyo.

Quién puede usarlo#

Paso a paso#

  1. En el panel, abre Configuración → Canales y, en la opción de conectar WhatsApp, toca Usar un número de heysteff. La opción aparece solo si tu plan lo incluye y hay números disponibles.
  2. En la ventana de heysteff deja marcada la opción «Usar un número de heysteff» y toca Continuar con Meta. Reservamos un número para ti durante 30 minutos.
  3. En la ventana de Meta, crea o elige tu cuenta de WhatsApp Business y, en el paso del número, elige el que aparece con el ícono de maletín: es el de heysteff. No elijas «Usar un número virtual» ni agregues otro número.
  4. Termina la conexión. El número queda conectado en Canales y ya puedes usarlo con POST /v1/messages como cualquier número de la Cloud API.

Si cierras la ventana antes de terminar, el número vuelve al pool y puedes intentar de nuevo.

Desde tu código (API, SDK y CLI)#

Puedes pedir el número desde tu código, pero no saltarte el paso de Meta: Meta solo deja un número en la cuenta de WhatsApp de un negocio dentro de su ventana de alta, con alguien que entra con Facebook y elige el número. La API reserva el número y te devuelve connect_url, el link de esa ventana. Ábrelo tú, o mándaselo a quien administra la cuenta de WhatsApp del negocio; al terminar, el número queda conectado en tu espacio.

  1. POST /v1/numbers reserva un número por 30 minutos y devuelve connect_url. El link es de un solo uso y vence en connect_url_expires_at. Si lo vuelves a pedir con una reserva viva, se reusa el mismo número, el plazo se renueva y el link es nuevo (reused: true).
  2. Alguien abre connect_url en un navegador y sigue los pasos 3 y 4 de arriba.
  3. GET /v1/numbers muestra el número con state: "connected" y su channel_connection_id, que usas en POST /v1/messages.
curl
# Reservar y obtener el link de conexión
curl -X POST https://app.heysteff.com/api/v1/numbers \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY"

# Ver tus números, el cupo del plan y si puedes pedir otro
curl https://app.heysteff.com/api/v1/numbers \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY"
JSON
{
  "data": {
    "number": {
      "id": "6f1c2a8e-3b4d-4e5f-9a0b-1c2d3e4f5a6b",
      "phone_number": "+15550100199",
      "country": "US",
      "state": "reserved",
      "reserved_until": "2026-11-05T12:30:00.000Z",
      "connected_at": null,
      "channel_connection_id": null,
      "display_name": { "name": null, "status": null, "rejection_reason": null, "requested_at": null }
    },
    "connect_url": "https://app.heysteff.com/connect/whatsapp?token=…&pool=1",
    "connect_url_expires_at": "2026-11-05T12:30:00.000Z",
    "reused": false
  }
}
TypeScript
import { Heysteff } from '@heysteff/sdk';

const heysteff = new Heysteff({ apiKey: process.env.HEYSTEFF_API_KEY });

const { number, connect_url } = await heysteff.numbers.reserve();
console.log(`Abre ${connect_url} para conectar ${number.phone_number}`);

const { data, plan } = await heysteff.numbers.list();
await heysteff.numbers.requestDisplayName(data[0].id, 'Tienda Aurora');
await heysteff.numbers.release(number.id); // solo si nadie lo conectó
Terminal
heysteff numbers reserve
heysteff numbers list
heysteff numbers display-name 6f1c2a8e-3b4d-4e5f-9a0b-1c2d3e4f5a6b "Tienda Aurora"
heysteff numbers release 6f1c2a8e-3b4d-4e5f-9a0b-1c2d3e4f5a6b
EndpointScopeQué hace
GET /v1/numbersnumbers:readTus números (reserved, connected o disconnected), el nombre visible y su revisión, el cupo del plan (plan.limit, plan.used) y si puedes pedir otro (offer).
GET /v1/numbers/{id}numbers:readUn número.
POST /v1/numbersnumbers:writeReserva un número y devuelve connect_url. 402 plan_limit si tu plan no incluye otro; 409 wa_pool_empty si no hay números ahora.
DELETE /v1/numbers/{id}numbers:writeSuelta una reserva que nadie conectó: el número vuelve al pool. Una reserva retenida porque el alta terminó en Meta sin confirmar el número responde 409 wa_pool_number_on_hold.
POST /v1/numbers/{id}/display-namenumbers:writePide a Meta un nombre visible nuevo ({"display_name": "…"}). Si Meta lo rechaza, responde 424 meta_display_name_rejected.

Un número conectado no se suelta por API. Ya está en tu cuenta de WhatsApp: si heysteff lo liberara, otra persona podría comprarlo y recibir los códigos de verificación de tu cuenta. DELETE responde 409 wa_pool_number_connected. Si quieres dejar de usarlo, desconecta el canal en Configuración → Canales y escríbenos a [email protected].

Las keys de prueba (sk_test_) no pueden pedir números: crea una key sk_live_ con los scopes numbers:read y numbers:write.

Nombre visible#

Al conectar, pedimos a Meta el nombre de tu negocio como nombre visible del número. Meta lo revisa y el estado aparece en Canales («Nombre visible»). Cuando lo aprueba, volvemos a registrar el número para que tus clientes vean el nombre nuevo. Puedes pedir otro nombre desde Canales («Cambiar el nombre visible»), con POST /v1/numbers/{id}/display-name o con el MCP.

Verificación, nombre visible y perfil de empresa#

Para cualquier número de WhatsApp Cloud de tu espacio (uno de heysteff o uno propio), con su channel_connection_id y una key sk_live_:

EndpointScopeQué hace
GET /v1/whatsapp-numbers/{id}numbers:readLa salud del número en vivo desde Meta: calidad (quality_rating: GREEN, YELLOW o RED), límite de mensajería (messaging_limit_tier), estado del número, el nombre visible y su revisión (display_name) y la verificación de la empresa (business_verification, con verify_url, el link del centro de seguridad de Meta Business donde se verifica). Si una parte falla, el resto responde igual y el motivo queda en errors.
GET /v1/whatsapp-numbers/{id}/business-profilenumbers:readEl perfil de empresa que ven tus clientes: about, description, address, email, websites, vertical y profile_picture_url.
PATCH /v1/whatsapp-numbers/{id}/business-profilenumbers:writeCambia los campos que mandes. La foto va en profile_picture_url: una URL https pública de un JPG o PNG (cuadrado, de 192×192 px o más, hasta 5 MB) o la url de POST /v1/media.
curl
curl -X PATCH https://app.heysteff.com/api/v1/whatsapp-numbers/3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d/business-profile \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "about": "Respondemos de lunes a sábado",
    "websites": ["https://tienda-aurora.cl"],
    "vertical": "RETAIL",
    "profile_picture_url": "https://tienda-aurora.cl/logo.png"
  }'

La verificación de la empresa no se hace por API: la pide Meta en su centro de seguridad (verify_url). El nombre visible de un número de heysteff se pide con POST /v1/numbers/{id}/display-name; el de un número propio, en WhatsApp Manager. En el SDK: heysteff.whatsappNumbers.get, getBusinessProfile y updateBusinessProfile; por MCP: get_whatsapp_number_status, get_whatsapp_business_profile y update_whatsapp_business_profile. Las llamadas del número se configuran en Llamadas de WhatsApp.

Quién cobra los mensajes#

Meta te cobra los mensajes directamente, con la tarjeta de tu cuenta de WhatsApp: heysteff no es Solution Partner de Meta y no factura esos mensajes. Agrega un medio de pago en el Administrador de WhatsApp antes de pasar el cupo gratis de Meta.

Desde tu IA (MCP)#

Tu IA reserva y te pasa el link; el paso de Meta lo termina una persona en el navegador.

Límites#