ONE whatsapp:create
← Receivers

whatsapp:create

whatsapp family

Create a workspace's own WhatsApp line: connect one WhatsApp Business number to a workspace, from a key. Proves the token owns that phone number id (a Graph read of the WhatsApp Business Account's numbers), seals the token and the number together on the workspace's whatsapp-cloud connection, which is what the channels webhook routes that number's messages by and what replies go out from. One number per workspace: connecting a new one retires the old. Refuses a number another workspace holds. Re-running it on the same number with a new token re-seals the token (rotated); a number the workspace retired can be connected again. Safe to re-run; dryRun checks the token and the number and names the number it would replace, writing nothing. The token is never echoed. Needs a Meta app and a WhatsApp Business Account the number lives in.

Effect
ask
Awaits an outcome — the call returns the response below.
Caller
manage_integrations
The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost
free
What one call costs, so you can budget before acting.
Reversible
no
This cannot be undone. Dry-run it first where the contract allows.
Idempotent
yes
Safe to retry as-is.
Version
1.0.0
Pin this to keep a contract stable; additive bumps never break callers.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code
Codex
Cursor
Gemini CLI
Claude Desktop
ChatGPT
curl -X POST https://one.ie/api/ask/whatsapp:create \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "phoneNumberId": "106540352242922", "wabaId": "102290129340398", "token": "…", "dryRun": true }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

  • phoneNumberId string required The phone number id from WhatsApp Manager (numeric, not the phone number itself)
  • wabaId string required The WhatsApp Business Account id the number belongs to (numeric)
  • token string required A system-user access token with whatsapp_business_messaging and whatsapp_business_management on that account. Sealed, never returned
  • workspace string optional The workspace to connect it to; defaults to the caller's own. Naming another (a client) needs control of it
  • dryRun boolean optional Check the token and the number only; write nothing

Response

What comes back from the call.

  • ok boolean
  • workspace string
  • phoneNumberId string
  • number string The display number Meta shows for it
  • name string The verified business name on the number
  • dryRun boolean
  • connection set | already | would_set | rotated The number's whatsapp-cloud connection row, holding the sealed token. rotated: the number was already this workspace's and the new token was re-sealed over the old
  • replaces string dryRun only: the phone number id the workspace has now, which connecting will retire, or 'token' when the number stays and only its sealed token would be replaced
  • replaced string The phone number id this run retired
  • error string forbidden · bad_request · no_db · bad_credentials · number_not_in_account · graph_unreachable · connection_failed · number_connected_elsewhere
  • cannot_run boolean
  • detail string

Traffic

Every call to whatsapp:create, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names whatsapp:create, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

API route 2
  • one.ie/web/src/lib/receiver-index.generated.ts:490
  • one.ie/web/src/lib/resolvers/whatsapp.ts:118
Agent runtime 1
  • channels/src/channels/whatsapp-tenant.ts:6
CLI 1
  • packages/cli/src/whatsapp.ts:24
→

Answered by

whatsapp:create one.ie/web/src/lib/resolvers/whatsapp.ts:111 Dispatched through POST /api/ask/whatsapp:create, after the envelope validates the payload.

whatsapp family · 2 more

JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "phoneNumberId": {
      "type": "string",
      "description": "The phone number id from WhatsApp Manager (numeric, not the phone number itself)"
    },
    "wabaId": {
      "type": "string",
      "description": "The WhatsApp Business Account id the number belongs to (numeric)"
    },
    "token": {
      "type": "string",
      "description": "A system-user access token with whatsapp_business_messaging and whatsapp_business_management on that account. Sealed, never returned"
    },
    "workspace": {
      "description": "The workspace to connect it to; defaults to the caller's own. Naming another (a client) needs control of it",
      "type": "string"
    },
    "dryRun": {
      "description": "Check the token and the number only; write nothing",
      "type": "boolean"
    }
  },
  "required": [
    "phoneNumberId",
    "wabaId",
    "token"
  ]
}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "workspace": {
      "type": "string"
    },
    "phoneNumberId": {
      "type": "string"
    },
    "number": {
      "description": "The display number Meta shows for it",
      "type": "string"
    },
    "name": {
      "description": "The verified business name on the number",
      "type": "string"
    },
    "dryRun": {
      "type": "boolean"
    },
    "connection": {
      "description": "The number's whatsapp-cloud connection row, holding the sealed token. rotated: the number was already this workspace's and the new token was re-sealed over the old",
      "type": "string",
      "enum": [
        "set",
        "already",
        "would_set",
        "rotated"
      ]
    },
    "replaces": {
      "description": "dryRun only: the phone number id the workspace has now, which connecting will retire, or 'token' when the number stays and only its sealed token would be replaced",
      "type": "string"
    },
    "replaced": {
      "description": "The phone number id this run retired",
      "type": "string"
    },
    "error": {
      "description": "forbidden · bad_request · no_db · bad_credentials · number_not_in_account · graph_unreachable · connection_failed · number_connected_elsewhere",
      "type": "string"
    },
    "cannot_run": {
      "type": "boolean"
    },
    "detail": {
      "type": "string"
    }
  },
  "required": [
    "ok"
  ]
}