Primeros pasos

Esta guía te lleva del cero a tu primer mensaje de WhatsApp enviado por la API.

Obtén tu API key

La API key se emite desde el dashboard, en Configuración → API. Tiene el prefijo sk_1to1_.

La API key da acceso completo a las conversaciones de tu negocio. Trátala como un secreto — nunca la pongas en código cliente ni la subas a un repositorio.

Identifica tu negocio

Todos los endpoints cuelgan de una base URL que incluye el {slug} de tu negocio:

https://app.1to1.ai/api/v1/public/{slug}

El {slug} también está en la configuración de la API. La key y el slug deben corresponder al mismo negocio.

Obtén la clave de tu canal

Todo request lleva la clave del canal (channel), obligatoria en cada envío. La copias del dashboard en Configuración → Canales: abre tu canal de WhatsApp y copia el campo Clave de canal (tiene el prefijo ch_). También puedes listarlas con GET /channels, que devuelve cada canal con su key.

La clave aparece al editar un canal ya conectado. Si acabas de crear uno, guárdalo y vuelve a abrirlo para verla.

Envía tu primer mensaje

Un POST a /conversation/actions con una acción send_message, y la conversación identificada por teléfono y canal:

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Hola 👋, ¿en qué te puedo ayudar?"
      }
    ]
  }'

const res = await fetch(
  "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_1to1_tu_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      conversation: { phone: "+5215512345678", channel: "ch_7A9K2M4Q" },
      actions: [
        { type: "send_message", body: "Hola 👋, ¿en qué te puedo ayudar?" },
      ],
    }),
  },
);

import requests

requests.post(
    "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
    headers={"Authorization": "Bearer sk_1to1_tu_api_key"},
    json={
        "conversation": {"phone": "+5215512345678", "channel": "ch_7A9K2M4Q"},
        "actions": [
            {"type": "send_message", "body": "Hola 👋, ¿en qué te puedo ayudar?"}
        ],
    },
)

Maneja la respuesta

Una respuesta 202 confirma que el grupo fue aceptado; las acciones corren en background:

{ "status": "processing", "actions_accepted": 1 }

El 202 no garantiza que cada acción haya tenido éxito — el resultado por acción no viaja en la respuesta. Consúltalo en el estado de la conversación o en el activity log del negocio.Si la validación falla, la API responde un 4xx síncrono y ninguna acción se ejecuta. Los errores devuelven { code, message }; ambos campos están garantizados. Haz switch sobre code (estable), nunca sobre message (texto humano, puede afinarse entre versiones):

{ "code": "CONVERSATION_NOT_FOUND", "message": "..." }

Rate limit: 60 requests/min por API key. Al excederlo recibes un 429 con el header Retry-After. Ver Rate limits.

Introducción

Conceptos

Guías

Acciones

Próximos pasos

Conversaciones

Mensajes

​Próximos pasos

Conversaciones

Mensajes

Próximos pasos