Update channel settings

PATCHhttps://api.wapito.com/v1/channel/settings

Send a channel token on every request: Authorization: Bearer wpt_YOUR_TOKEN

Changes the behaviour flags applied to every request on this channel: the spacing between queued sends, typing simulation, automatic read receipts, automatic call rejection, whether raw engine payloads are attached to webhook events, and the outbound proxy. Only the fields you send are changed. Setting a proxy requires a premium channel and restarts the engine session, which briefly disconnects the number.

Request body

Fields of the request body
FieldTypeRequiredDescription
auto_readbooleanOptionalMark inbound messages as read automatically.
include_rawbooleanOptionalAttach the untouched engine payload as `raw` on webhook events.
namestringOptionalChannel name shown in the dashboard.
proxyobject | nullOptionalOutbound proxy for the engine, or `null` to clear it. Premium only.
passwordstring | nullOptionalProxy password. Write-only: reads return `null`.
urlstringRequiredProxy URL, for example `http://gw.proxy.example:8000`.
usernamestring | nullOptionalProxy username.
reject_callsbooleanOptionalReject incoming WhatsApp calls automatically.
send_delay_msintegerOptionalSpacing between queued sends, minimum 500 on sandbox.min 500
typing_simulationstringOptional`auto` types before each send, `off` sends immediately.one of off, auto
{
  "reject_calls": true,
  "send_delay_ms": 2500,
  "typing_simulation": "auto"
}

Responses

200

Settings after the change.

Fields of the 200 response
FieldTypeRequiredDescription
connected_atstring | nullRequiredISO 8601 timestamp of the current link.date-time
created_atstring | nullRequiredISO 8601 timestamp the channel was created.date-time
enginestringRequiredProtocol engine running this channel.one of gows, noweb
idstringRequiredChannel id (`ch_` + ULID).
last_seen_atstring | nullRequiredISO 8601 timestamp of the last engine heartbeat.date-time
lidstring | nullRequiredLID of the linked account.
namestringRequiredName you gave the channel in the dashboard.
phonestring | nullRequiredLinked phone number in digits, once connected.
planstringRequiredBilling plan in force.one of sandbox, premium
push_namestring | nullRequiredProfile name the linked account publishes.
settingsobjectRequiredPer-channel behaviour flags, including the anti-ban knobs described in the sending guide.
auto_readbooleanRequiredMark inbound messages as read automatically.
include_rawbooleanRequiredAttach the untouched engine payload as `raw` on webhook events.
proxyobject | nullRequiredOutbound proxy, or `null` for a direct connection.
passwordstring | nullOptionalProxy password. Write-only: reads return `null`.
urlstringRequiredProxy URL, for example `http://gw.proxy.example:8000`.
usernamestring | nullOptionalProxy username.
reject_callsbooleanRequiredReject incoming WhatsApp calls automatically.
send_delay_msintegerRequiredSpacing between queued sends in milliseconds; minimum 500 on sandbox.
typing_simulationstringRequired`auto` types for roughly 60 ms per character before sending, capped at 8 s.one of off, auto
statusstringRequiredConnection state mirrored from the engine session.one of created, qr, pairing, connected, disconnected, logged_out, banned
webhooks_countintegerRequiredNumber of configured webhooks.
{
  "connected_at": "2026-09-04T10:22:31.000Z",
  "created_at": "2026-09-04T10:19:02.000Z",
  "engine": "gows",
  "id": "ch_01JRQ8F4X9N2K7YB3C5V6W8H0T",
  "last_seen_at": "2026-09-15T07:41:08.000Z",
  "lid": "992814736450921@lid",
  "name": "Acme Support",
  "phone": "15557654321",
  "plan": "premium",
  "push_name": "Acme Support",
  "settings": {
    "auto_read": false,
    "include_raw": false,
    "proxy": null,
    "reject_calls": true,
    "send_delay_ms": 1500,
    "typing_simulation": "auto"
  },
  "status": "connected",
  "webhooks_count": 2
}

400

The request body or query string is malformed, or the recipient cannot be parsed into a WhatsApp id.

Show 2 example bodies

invalid_recipient — `to` is not a dialable number or valid WhatsApp id

{
  "error": {
    "code": "invalid_recipient",
    "details": {
      "to": "+1555"
    },
    "message": "The recipient is not a valid WhatsApp address.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

invalid_request — schema validation failed

{
  "error": {
    "code": "invalid_request",
    "details": {
      "issues": [
        {
          "message": "Array must contain at least 2 element(s)",
          "path": "body.options"
        }
      ]
    },
    "message": "The request payload failed validation.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

401

The channel token is missing, malformed, revoked or belongs to a deleted channel.

Show 2 example bodies

token_revoked — the token was rotated in the dashboard

{
  "error": {
    "code": "token_revoked",
    "message": "This channel token has been revoked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

unauthorized — no or unusable Bearer token

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid channel token.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

402

A cap that a higher plan lifts was reached (Sandbox: one channel, two webhooks, no proxy). `details.checkout_url` is the dashboard page that starts the upgrade; `details.plan` names the plan that refused, `details.limit` the cap it applied (for counted features) and `details.price_ids` the Stripe prices, so a client can start Checkout itself. A cap no plan lifts (five webhooks on Premium) is `429 quota_exceeded` instead.

Show the example body

plan_required — upgrade needed, `checkout_url` included

{
  "error": {
    "code": "plan_required",
    "details": {
      "checkout_url": "https://wapito.com/app/?upgrade=1",
      "feature": "webhooks",
      "limit": 2,
      "plan": "sandbox",
      "price_ids": {
        "monthly": "price_1S0aBcDeFgHiJkLmMONTHLY",
        "yearly": "price_1S0aBcDeFgHiJkLmYEARLY"
      }
    },
    "message": "This action requires a Premium channel.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

403

The token is valid but the channel may not perform this action right now.

Show 2 example bodies

channel_locked — billing lapsed or the channel was locked by an operator

{
  "error": {
    "code": "channel_locked",
    "details": {
      "reason": "plan_required"
    },
    "message": "This channel is locked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

forbidden — the channel does not own the target object

{
  "error": {
    "code": "forbidden",
    "message": "You are not allowed to perform this action.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

409

The channel is in the wrong state for this action, or the account type does not support it.

Show 3 example bodies

business_account_required — labels need WhatsApp Business

{
  "error": {
    "code": "business_account_required",
    "message": "This action requires a WhatsApp Business account.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_connected — link the number first

{
  "error": {
    "code": "channel_not_connected",
    "details": {
      "status": "qr"
    },
    "message": "The channel is not connected.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_in_qr_state — no QR available while the session boots

{
  "error": {
    "code": "channel_not_in_qr_state",
    "details": {
      "status": "created"
    },
    "message": "The channel is not waiting for a QR scan.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

429

A rate limit, a plan quota or one of the anti-ban guards stopped the request. Every one of these is safe to retry later; read `Retry-After` when present.

Show 5 example bodies

cold_send_limit — too many first messages to new recipients this hour

{
  "error": {
    "code": "cold_send_limit",
    "details": {
      "resets_at": "2026-09-15T09:00:00.000Z",
      "window_cap": 20
    },
    "message": "The hourly limit for messages to new recipients is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

quota_exceeded — plan quota for the day or month

{
  "error": {
    "code": "quota_exceeded",
    "details": {
      "quota": "sent",
      "resets_at": "2026-09-16T00:00:00.000Z",
      "used": 150
    },
    "message": "The plan quota for this resource is exhausted.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

rate_limited — per-minute API rate limit

{
  "error": {
    "code": "rate_limited",
    "details": {
      "retry_after": 12
    },
    "message": "Too many requests.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

send_rate_limited — the send queue did not drain within 20 s

{
  "error": {
    "code": "send_rate_limited",
    "details": {
      "retry_after": 5
    },
    "message": "The send queue for this channel is saturated.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

warmup_limit — the warm-up ladder cap for today

{
  "error": {
    "code": "warmup_limit",
    "details": {
      "cap": 200,
      "day": 2
    },
    "message": "The warm-up limit for this channel is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

500

Something went wrong inside Wapito. Quote `request_id` when reporting it.

Show the example body

internal_error — unexpected failure

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

502

The engine answered with an error Wapito could not translate into a more specific code.

Show the example body

engine_error — unexpected engine failure

{
  "error": {
    "code": "engine_error",
    "details": {
      "engine": "gows",
      "status": 500
    },
    "message": "The WhatsApp engine returned an error.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

503

The engine session is not reachable. Retry with backoff.

Show the example body

engine_unavailable — engine down or restarting

{
  "error": {
    "code": "engine_unavailable",
    "details": {
      "engine": "gows"
    },
    "message": "The WhatsApp engine is unavailable.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

504

The engine did not answer before the upstream timeout.

Show the example body

engine_timeout — no answer within the deadline

{
  "error": {
    "code": "engine_timeout",
    "details": {
      "timeout_ms": 20000
    },
    "message": "The WhatsApp engine did not respond in time.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

Webhook events

  • channelChannel connection state changedonChannel()

Errors

Code examples

import requests

url = "https://api.wapito.com/v1/channel/settings"

payload = {
    "send_delay_ms": 2500,
    "typing_simulation": "auto",
    "reject_calls": True
}
headers = {
    "Authorization": "Bearer wpt_YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())

Used in

Related

Try it on your own number

Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.