Quickstart

This guide takes you from zero to your first WhatsApp message sent through the API.

Get your API key

The API key is issued from the dashboard, under Settings → API. It has the sk_1to1_ prefix.

The API key grants full access to your business’s conversations. Treat it as a secret — never put it in client-side code or commit it to a repository.

Identify your business

Every endpoint hangs off a base URL that includes your business’s {slug}:

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

The {slug} is also in the API settings. The key and the slug must belong to the same business.

Get your channel key

Every request carries the channel key (channel), required on each send. You copy it from the dashboard under Settings → Channels: open your WhatsApp channel and copy the Channel key field (it has the ch_ prefix). You can also list them with GET /channels, which returns each channel with its key.

The key appears when you edit an already-connected channel. If you just created one, save it and reopen it to see the key.

Send your first message

A POST to /conversation/actions with a send_message action, and the conversation identified by phone and channel:

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "send_message",
        "body": "Hi 👋, how can I help you?"
      }
    ]
  }'

const res = await fetch(
  "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_1to1_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      conversation: { phone: "+5215512345678", channel: "ch_7A9K2M4Q" },
      actions: [
        { type: "send_message", body: "Hi 👋, how can I help you?" },
      ],
    }),
  },
);

import requests

requests.post(
    "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions",
    headers={"Authorization": "Bearer sk_1to1_your_api_key"},
    json={
        "conversation": {"phone": "+5215512345678", "channel": "ch_7A9K2M4Q"},
        "actions": [
            {"type": "send_message", "body": "Hi 👋, how can I help you?"}
        ],
    },
)

Handle the response

A 202 response confirms the group was accepted; the actions run in the background:

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

The 202 does not guarantee each action succeeded — the per-action result does not travel in the response. Check it in the conversation status or the business’s activity log.If validation fails, the API returns a synchronous 4xx and no action runs. Errors return { code, message }; both fields are guaranteed. Switch on code (stable), never on message (human text, may be refined between API versions):

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

Rate limit: 60 requests/min per API key. When exceeded you get a 429 with the Retry-After header. See Rate limits.

Introduction

Concepts

Guides

Actions

Next steps

Conversations

Messages

​Next steps

Conversations

Messages

Next steps