Business API

Required permission: Account info (account:view)

Reads current account authority. Account reads remain available while paused, suspended or banned. This grants no permission to send.

No request body.

Successful response

Read the authenticated Business account: response fields: features

Read the authenticated Business account: response fields: verified

Variant 1

The verified-business badge (Natter D405): when Masons Mail approved it and the plain facts it confirmed. Natter apps that read presentation level 8 receive the same value.

Read the authenticated Business account: response fields: customer_link

D423: the customer link of this environment (Business API 0.10.0).

Responses

200

Current account metadata.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Profile & appearance (profile:manage)

Returns the customer-facing display name, description, support contacts, address and links. The registered account name remains separate. This read never returns the private operational contact or asserts company verification. Keys require Profile & appearance (profile:manage) in their own environment. Live, Test and the owner portal share this saved profile and revision. The flat public body is unchanged; use the strong ETag header for a conditional PUT. Historical saved records remain readable even if they exceed the new write aggregate limit.

No request body.

Successful response

Read your public Business profile: response fields: address

Read your public Business profile: response fields: links[]

Response headers

ETag

Opaque strong validator bound to this business and profile revision. Keep the quotes when sending If-Match.

Responses

200

Only public profile fields. Optional fields are empty strings or arrays.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Profile & appearance (profile:manage)

Requires a full-access key or a restricted key with Profile & appearance (profile:manage). Live, Test and the owner portal edit the same saved profile. Send all public fields with the exact strong ETag returned by GET in If-Match; no weak, wildcard, multiple or wrong-business validators. Never include the private operational contact: it is rejected and cannot be changed by this API. Missing If-Match returns 428; stale revisions return 412. Read and reconcile before retrying after a conflict or lost response. Key, owner and selected verified sender authority are checked again in the transaction. JSON body limit: 32768 bytes. New public objects must serialize to at most 15360 UTF-8 bytes using compact JSON.stringify-compatible escaping, within the existing 16384-byte database record bound. Text bounds count UTF-16 code units; display name also has a 256 UTF-8-byte limit. HTTPS URLs require a nonempty host, no credentials, whitespace or backslashes, a valid explicit port 1-65535 if supplied, and at most 2048 UTF-8 bytes. All declared fields, address fields and link fields are required; optional values are empty strings or arrays. Nulls, duplicate or unknown fields and invalid Unicode are rejected.

If-Match (header, required): Exact strong ETag from this business's last profile GET, including quotes. See the full schema for validation rules.

JSON request

Send one JSON object with only the fields below.

Update your saved public Business profile: request fields: address

Update your saved public Business profile: request fields: links[]

Successful response

Update your saved public Business profile: response fields: address

Update your saved public Business profile: response fields: links[]

Response headers

ETag

New strong validator for the saved revision.

Responses

200

Saved public profile. Private operational contact remains unchanged.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks Profile & appearance (profile:manage), belongs to another environment, or current owner or selected sender authority no longer permits access.

405

The method is not supported for this exact route.

412

The profile changed after the supplied ETag. Read, reconcile and retry with the new validator.

422

The display name uses a reserved name (Masons Mail, Natter, Idelego, an authority such as police or a tax agency, or official support for one of them) or a banned word. Nothing was saved or charged. Masons Mail can allow a name for a business on request.

428

If-Match is required. Read the profile to obtain its ETag.

429

business_save_limit: the business has used today’s saves. Per UTC calendar day a business may make 5 text saves (profile, colours, features and visibility together) and 2 picture uploads (avatar, chat wallpaper, profile background), 1 once it has more than 100,000 customers. Live, Test and the owner portal share these budgets. Nothing was written. Wait Retry-After seconds (until the next UTC midnight), then send the same request again.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Requires the current customer relationship in this environment, an eligible customer message less than 183 elapsed days (4392 hours) ago, an active/throttled business and current key/endpoint/account/member authority. Merely opening a chat, receipts and background updates do not renew permission. Opt-out and independent blocks prevent a new send. The required runtime admission callback additionally controls commissioning and sandbox recipients; setup is still required for each environment. First acceptance creates sealed queued work, not a sent/delivered/read claim. Matching retries require the same API key and unchanged recipient/type/text/media_id within the 24-hour idempotency window and still-current permission; HTTP 200 returns the same operation ID with current state. A different API key cannot adopt old work. Retry never extends deadlines. A retained expired key returns idempotency_expired; after bounded idempotency cleanup the server can no longer deduplicate it, so never rely on replay protection beyond 24 hours. Media requests reference a ready upload from POST media; they do not contain file bytes or URLs. The upload must belong to the same key and contact, and its feature must still be enabled. Both variants return the same receipt and sent/failed/read status contract; no delivered status is emitted.

Idempotency-Key (header, required): Exactly one header. 1–200 visible ASCII characters (0x21–0x7e); no spaces. Scoped to this Business/environment. Use a new value for a distinct send. Minimum characters: 1. Maximum characters: 200.

JSON request

At most 32,768 UTF-8 bytes for the complete JSON body; unknown/duplicate/case-aliased fields are invalid.

Text message

Media message

Successful response

Responses

200

Matching idempotent replay; original operation identity and deadlines are preserved.

202

New request durably queued. It has not yet been accepted by the relay.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

402

payment_required: the Live price is positive and this business's prepaid credit or invoice credit limit cannot cover the send.

403

Permission/environment mismatch, paused or suspended/banned business, or current customer relationship/endpoint permission prevents this send. Banned sending uses business_suspended.

405

The method is not supported for this exact route.

409

The recipient/text differs under a retained request key, or its retained 24-hour replay deadline has expired.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Returns content-free state for this Business/environment, using a current key with Messaging & calls (messaging:manage, or an older key's converted messages:send). It need not be the original sending key. No message body, phone number, hosted device identity, history or cryptographic state is returned. Receipts remain available for at most 30 days from creation; removal of required account/contact parents can shorten availability. Unknown, expired and foreign operations share the same 404.

No request body.

Successful response

Responses

200

Current operation receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

404

Unknown, expired, foreign or non-outbound operation, or noncanonical message UUID.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Webhook (webhooks:manage)

Requires the current scoped key. Maintenance/read access remains available while paused, suspended or banned. No signing secret is returned. A missing configuration returns HTTP 200 with webhook:null.

No request body.

Successful response

Read webhook metadata: response fields: webhook

Variant 1

Responses

200

Current metadata or null.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Webhook (webhooks:manage)

Every successful PUT, including an identical replay, rotates the secret and advances the database revision. This operation has no Idempotency-Key replay contract. The signing secret is returned once after commit; losing that response requires another rotation. GET never recovers it. The HTTPS destination is syntax/public-address validated and DNS checked before the write; no test message is posted. Dispatch resolves and pins public DNS again. Rotation does not readdress previously queued content to the new revision: old-revision payload is disposed by bounded cleanup. Maintenance remains allowed while paused/suspended/banned, without authorizing delivery.

JSON request

At most 16,384 bytes of strict UTF-8 JSON.

Successful response

Set destination and rotate its signing secret: response fields: webhook

Responses

200

Persisted destination metadata and one-time signing secret.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Webhook (webhooks:manage)

Idempotent deletion of this Business/environment's configuration. Missing configuration also returns 204. Legacy and other environment rows are unchanged. Queued content is not rerouted; bounded cleanup disposes its now-missing destination. No response body.

No request body.

Responses

204

Configuration is absent.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Account info (account:view)

Read-only. Lists every number of the business with its verification state and the environments that send from it. Phone numbers are never returned. Add, verify, label or remove numbers in the Business portal.

No request body.

Successful response

List the business's numbers: response fields: numbers[]

A business phone number as metadata only. The number itself is never returned by the API.

Responses

200

Current numbers, oldest first.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Account info (account:view)

Read-only. Lists up to 100 keys of this environment, newest first, including revoked keys. Secrets are never returned. Create, replace or revoke keys in the Business portal.

No request body.

Successful response

List this environment's API keys: response fields: keys[]

API key metadata. The secret, its hash and salt are never returned.

Responses

200

Key metadata.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Webhook (webhooks:manage)

Sends one test event to the configured endpoint through the normal delivery path: the same destination checks, X-Natter-Signature, X-Natter-Event-Id and ten-second limit as customer events. It is a single attempt and is not retried; the result is returned and recorded in the delivery log. Send no request body. At most ten tests per minute per environment. Maintenance remains allowed while paused, suspended or banned.

No request body.

Successful response

Send a signed test event: response fields: test

One POST to your endpoint. No payload, URL or response body is kept.

Responses

200

The attempt, delivered or not.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

409

No webhook is configured for this environment.

429

Ten tests were already sent in the last minute.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Webhook (webhooks:manage)

The last 50 attempts of this environment from the last seven days, newest first: event kind and ID, attempt number, HTTP status, latency and failure code. Payloads are never stored.

No request body.

Successful response

List recent webhook delivery attempts: response fields: deliveries[]

One POST to your endpoint. No payload, URL or response body is kept.

Responses

200

Recent attempts.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

Read only this business and environment using Billing (billing:read). Month-to-date totals, seven-day processing metrics and monthly history (the current month unless month or from/to is given). Available during a price hold; never grants sending permission.

month (query, optional): One UTC month, YYYY-MM. Not in the future and at most 36 months back. See the full schema for validation rules.

from (query, optional): First month of a range, YYYY-MM; use with to. A range covers at most 12 months. See the full schema for validation rules.

to (query, optional): Last month of a range, YYYY-MM; not in the future. See the full schema for validation rules.

No request body.

Successful response

Read usage and processing metrics: response fields: usage_period

Month-to-date UTC ledger period.

Read usage and processing metrics: response fields: metrics_period

Rolling seven-day operational period.

Read usage and processing metrics: response fields: pricing

Read usage and processing metrics: response fields: usage

Durable accepted outbound units and recorded price; zero-price events count.

Read usage and processing metrics: response fields: traffic

Content-free operation counts in the operational period.

Read usage and processing metrics: response fields: processing

Submission to server acceptance for accepted outbound samples; milliseconds, null without samples. Not phone delivery latency.

Read usage and processing metrics: response fields: webhooks

Current pending queue, failures retained within seven days, and retry attempts among those retained rows. Not lifetime webhook totals.

Read usage and processing metrics: response fields: daily[]

Read usage and processing metrics: response fields: history

Monthly usage for the requested months, oldest first.

Read usage and processing metrics: response fields: history: months[]

One month of metered usage.

Read usage and processing metrics: response fields: history: months[]: outbound_by_type

Read usage and processing metrics: response fields: history: months[]: outbound_by_type: text

Read usage and processing metrics: response fields: history: months[]: outbound_by_type: image

Read usage and processing metrics: response fields: history: months[]: outbound_by_type: document

Read usage and processing metrics: response fields: history: months[]: outbound_by_type: audio

Read usage and processing metrics: response fields: history: months[]: outbound_by_type: video

Responses

200

Read usage and processing metrics.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

Read only this business and environment using Billing (billing:read). Available during a price hold; never grants sending permission.

No request body.

Successful response

Read current message pricing: response fields: pricing

Responses

200

Read current message pricing.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

Mode (prepaid or monthly invoice), balance, credit limit, low-balance warning and whether payment is required, for this business and environment. Mode and limits cannot be changed through the API.

No request body.

Successful response

Read the billing account: response fields: billing

Billing account for this business and environment. Mode and limits are changed by Masons Mail or in the portal, never through the API.

Read the billing account: response fields: pricing

Responses

200

Read the billing account.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

Newest first: one usage debit per accepted send at the price in force, plus top-ups, adjustments and invoice payments.

limit (query, optional): Page size, 1 to 100 (default 50). Minimum: 1. Maximum: 100.

before (query, optional): The next value from the previous page. Maximum characters: 64.

No request body.

Successful response

List balance movements: response fields: ledger

List balance movements: response fields: ledger: entries[]

One balance movement.

Responses

200

List balance movements.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

Up to 36 monthly records for this business and environment, newest first. Empty until a month with usage or a billing account has closed.

No request body.

Successful response

List invoices: response fields: invoices[]

One record per closed UTC month, totalled from the same usage ledger as /usage. Issued about one hour after the month ends.

List invoices: response fields: invoices[]: lines[]

Responses

200

List invoices.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Billing (billing:read)

One monthly record with its lines.

No request body.

Successful response

Read one invoice: response fields: invoice

One record per closed UTC month, totalled from the same usage ledger as /usage. Issued about one hour after the month ends.

Read one invoice: response fields: invoice: lines[]

Responses

200

Read one invoice.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment.

404

not_found: no invoice with this id in this business/environment.

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Profile & appearance (profile:manage)

Whether the business is listed in the Natter app's business search (the owner's switch, on by default), whether Masons Mail has unlisted it, whether it is searchable now and, if not, what is missing. A name close to an earlier-verified business is marked similar_to_verified: it is still listed but labelled and ranked below that business.

No request body.

Successful response

Responses

200

The current listing.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key scope, owner or business authority does not permit this request.

404

not_found: the environment is not live.

405

The method is not supported for this exact route.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Send exactly {"listed": true} or {"listed": false}. A change counts as one of the day's text saves (shared with profile and settings saves); sending the current value changes and charges nothing. Masons Mail's own unlisting cannot be undone here. Unlisted businesses stay reachable by their link, QR code and exact business number.

JSON request

Send one JSON object with only the fields below.

Successful response

Responses

200

The saved listing.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key scope, owner or business authority does not permit this request.

404

not_found: the environment is not live.

405

The method is not supported for this exact route.

429

business_save_limit: the business has used today’s saves. Per UTC calendar day a business may make 5 text saves (profile, colours, features and visibility together) and 2 picture uploads (avatar, chat wallpaper, profile background), 1 once it has more than 100,000 customers. Live, Test and the owner portal share these budgets. Nothing was written. Wait Retry-After seconds (until the next UTC midnight), then send the same request again.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Current settings for this business and environment. Missing configuration returns revision zero and media/call switches off. Private contacts are not part of this document.

No request body.

Successful response

Read appearance, visibility and feature settings: response fields: settings

Read appearance, visibility and feature settings: response fields: settings: features

Read appearance, visibility and feature settings: response fields: settings: appearance

Read appearance, visibility and feature settings: response fields: settings: visibility

Response headers

ETag

Strong settings revision validator, for example "business-settings-3".

Responses

200

Current settings. Treat the ETag as opaque and keep it with this business/environment.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner or selected sender authority does not permit this request.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Updates the same saved settings as the portal. Send all fields, the expected_revision from GET, and that GET response ETag as If-Match. Hidden values are removed from consumer responses without erasing the owner's saved profile. An asset must belong to the exact business, environment and slot. Textual profile values are business-wide; these settings are environment-specific.

If-Match (header, required): The strong ETag returned by the corresponding settings GET. See the full schema for validation rules.

JSON request

Complete settings document; at most 24,576 UTF-8 bytes. No missing, duplicate, unknown or null flags.

Save appearance, visibility and feature settings: request fields: settings

Save appearance, visibility and feature settings: request fields: settings: features

Save appearance, visibility and feature settings: request fields: settings: appearance

Save appearance, visibility and feature settings: request fields: settings: visibility

Successful response

Save appearance, visibility and feature settings: response fields: settings

Save appearance, visibility and feature settings: response fields: settings: features

Save appearance, visibility and feature settings: response fields: settings: appearance

Save appearance, visibility and feature settings: response fields: settings: visibility

Response headers

ETag

Strong settings revision validator, for example "business-settings-3".

Responses

200

Saved settings and the next revision.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner or selected sender authority does not permit this request.

404

Selected asset is missing, expired or not owned by this business/environment/slot.

409

business_settings_changed: a concurrent edit changed the revision. Read and reconcile before a deliberate retry.

412

precondition_failed: If-Match does not exactly match expected_revision.

428

precondition_required: If-Match is missing.

429

business_save_limit: the business has used today’s saves. Per UTC calendar day a business may make 5 text saves (profile, colours, features and visibility together) and 2 picture uploads (avatar, chat wallpaper, profile background), 1 once it has more than 100,000 customers. Live, Test and the owner portal share these budgets. Nothing was written. Wait Retry-After seconds (until the next UTC midnight), then send the same request again.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

The optional screen the Natter app shows after Natter's own fixed Business notice, for this business and environment. Missing configuration returns revision zero and welcome null.

No request body.

Successful response

Read the welcome and terms screen: response fields: welcome

Variant 1

Response headers

ETag

Strong welcome revision validator, for example "business-welcome-3".

Responses

200

Current welcome screen. Keep the ETag with this business/environment.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key scope, owner or selected sender authority does not permit this request.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Send expected_revision from GET and that response's ETag as If-Match. A save is one of the day's text saves. Changing the text or a link changes content_version; with reask_on_change, customers who agreed earlier must agree again before either side can send new messages.

If-Match (header, required): The strong ETag returned by the corresponding welcome GET. See the full schema for validation rules.

JSON request

Complete welcome document; at most 16,384 UTF-8 bytes. No missing, duplicate or unknown fields.

Save the welcome and terms screen: request fields: welcome

Variant 1

Successful response

Save the welcome and terms screen: response fields: welcome

Variant 1

Response headers

ETag

Strong welcome revision validator, for example "business-welcome-3".

Responses

200

Saved welcome screen and the next revision.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key scope, owner or selected sender authority does not permit this request.

409

business_settings_changed: a concurrent edit changed the welcome revision. Read and reconcile before a deliberate retry.

412

precondition_failed: If-Match does not exactly match expected_revision.

428

precondition_required: If-Match is missing.

429

business_save_limit: the business has used today’s saves. Per UTC calendar day a business may make 5 text saves (profile, colours, features and visibility together) and 2 picture uploads (avatar, chat wallpaper, profile background), 1 once it has more than 100,000 customers. Live, Test and the owner portal share these budgets. Nothing was written. Wait Retry-After seconds (until the next UTC midnight), then send the same request again.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

POST raw JPEG/PNG bytes to assets/avatar, assets/chat_wallpaper or assets/profile_background. At most 2 MiB, 4 megapixels and 4096 pixels per side; normalized avatars at most 512 KiB. Metadata is stripped by decoding/re-encoding. Upload does not publish: set the returned id in appearance via PUT settings. Unselected uploads expire after 24 hours. Tenant/environment capacity is 512 assets or 256 MiB. No remote image URLs are accepted.

Upload request

Raw image bytes; this is not JSON, base64 or multipart.

Content-Type: image/jpeg or image/png

Successful response

Responses

201

Normalized asset metadata. Save its ID in the matching settings slot.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner or selected sender authority does not permit this request.

413

business_asset_limit: input, normalized image or tenant capacity exceeds its limit.

429

business_save_limit: the business has used today’s saves. Per UTC calendar day a business may make 5 text saves (profile, colours, features and visibility together) and 2 picture uploads (avatar, chat wallpaper, profile background), 1 once it has more than 100,000 customers. Live, Test and the owner portal share these budgets. Nothing was written. Wait Retry-After seconds (until the next UTC midnight), then send the same request again.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Returns an owned, unexpired normalized image. Customers use their authenticated conversation asset route and may read only currently selected images.

If-None-Match (header, optional): The ETag of a copy you already hold. Asset IDs are immutable, so a matching validator returns 304 without the image. See the full schema for validation rules.

No request body.

Successful response

Content-Type: image/jpeg.

Content-Type: image/png.

Response headers

Cache-Control

private, max-age=31536000, immutable. Private because every read is authorized for its caller; never store it in a shared cache.

ETag

Strong validator for this asset ID, for example "business-asset-<asset UUID>".

Responses

200

Raw normalized image. Asset IDs are immutable: a changed picture is a new ID, so the response may be kept privately for a year.

304

If-None-Match matched this asset's ETag after authorization. No body; keep using your copy.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner or selected sender authority does not permit this request.

404

business_asset_not_found: no matching owned, unexpired asset.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Profile & appearance (profile:manage)

Deletes an owned asset only when no current or retained settings revision references it. Replacing a setting may retain its previous image for bounded rollback; no customer can read that image once it is no longer selected.

No request body.

Responses

204

Unused asset deleted.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner or selected sender authority does not permit this request.

404

business_asset_not_found.

409

business_asset_in_use: a retained settings revision still references the image.

503

Business settings are temporarily unavailable (business_settings_unavailable or business_unavailable). temporarily_unavailable (D393): the business owner authority lease lapsed moments ago and is being renewed; it always carries Retry-After: 5. Nothing was written. Retry the same request after Retry-After when it is present.

Required permission: Messaging & calls (messaging:manage)

Exactly two multipart parts: metadata JSON first, file binary second; reject extra parts and Content-Encoding. Metadata is at most 16,384 bytes. File limits: image/document/audio 26,214,400 bytes, video 47,185,920 bytes; complete HTTP body at most 47,218,688 bytes. Images must be JPEG/PNG with matching dimensions; MP4 must contain ftyp and mdat. For audio/mp4, duration/waveform are bounded caller metadata. A voice note may instead be uploaded as audio/ogg (Opus in Ogg, as WhatsApp and most TTS engines produce): the server checks that the bytes really are one complete Ogg/Opus stream, converts it once, before encryption, to mono AAC-LC m4a (24 kHz, 32 kbit/s), measures duration_ms and the 48-level waveform itself, and stores and delivers only the m4a; the response describes the converted file. Unsupported or corrupt audio answers 415 unsupported_audio; a note over 1 hour answers 422 audio_too_long. Upload is bound to this exact key, business, environment and contact. It does not send a message: POST messages with the returned media_id before expires_at. Two transfer slots per API runtime, within the 16-request pool; absolute 120-second transfer deadline.

Upload request

Send metadata first as application/json, then file as binary with its declared MIME. Exactly two parts, in that order. No Content-Encoding.

Content-Type: multipart/form-data

Upload media for one customer: multipart fields: metadata

Image upload metadata

File body must contain 1..26,214,400 bytes. Send the metadata JSON part before the file part.

Document upload metadata

File body must contain 1..26,214,400 bytes. Send the metadata JSON part before the file part.

Audio upload metadata

File body must contain 1..26,214,400 bytes. Send the metadata JSON part before the file part.

Voice note (Ogg/Opus) upload metadata

File body must contain 1..26,214,400 bytes of one complete Ogg/Opus stream, at most 1 hour long. Omit duration_ms, waveform, width and height: the server converts the note to mono AAC-LC audio/mp4 and measures duration and waveform from the decoded audio. Send the metadata JSON part before the file part.

Video upload metadata

File body must contain 1..47,185,920 bytes. Send the metadata JSON part before the file part.

Part metadata Content-Type: application/json.

Part file Content-Type: */*.

Successful response

Width and height occur only for image/video; duration_ms only for audio/video. No waveform, content URL, descriptor or encryption key is returned. An audio/ogg voice upload is described as the converted file: mime_type audio/mp4, the .m4a name, the converted byte count and the measured duration_ms.

Responses

201

Ready upload metadata. Use this exact key and recipient for the subsequent message.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner, verified selected number, customer permission, block or feature setting does not permit this operation.

404

not_found: no currently accessible resource in this business/environment.

415

unsupported_audio: metadata.mime_type is audio/ogg but the file is not one complete, decodable Opus stream in Ogg (for example Vorbis or FLAC in Ogg, Opus in WebM, an MP4, a truncated or damaged file, or chained streams). Nothing was stored. Send real Ogg/Opus, or upload audio/mp4 instead.

422

audio_too_long: an audio/ogg voice note is longer than 3,600,000 ms (1 hour), measured from the stream and again from the decoded audio. Nothing was stored.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Current key, owner, selected verified number, business/environment, contact window, block and feature permissions are checked again before decrypted reads. Outbound handles are private to the exact uploading key; any current key with Messaging & calls (messaging:manage, or an older key's converted messages:send) in the same business/environment can read an admitted inbound handle. A handle does not grant permission or renew the contact window.

No request body.

Successful response

Width and height occur only for image/video; duration_ms only for audio/video. No waveform, content URL, descriptor or encryption key is returned. An audio/ogg voice upload is described as the converted file: mime_type audio/mp4, the .m4a name, the converted byte count and the measured duration_ms.

Responses

200

Ready media metadata; no plaintext file content.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner, verified selected number, customer permission, block or feature setting does not permit this operation.

404

not_found: no currently accessible resource in this business/environment.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Current key, owner, selected verified number, business/environment, contact window, block and feature permissions are checked again before decrypted reads. Outbound handles are private to the exact uploading key; any current key with Messaging & calls (messaging:manage, or an older key's converted messages:send) in the same business/environment can read an admitted inbound handle. A handle does not grant permission or renew the contact window. Inbound only; outbound upload bytes are not exposed. Download before expires_at, validate the response and durably retain required bytes on your own server before ACK. Absolute 120-second deadline and two shared transfer slots. No redirect or public media URL.

No request body.

Successful response

Content-Type: */*.

Response headers

Content-Type

Validated original media MIME type, also present in media metadata.

Content-Disposition

attachment; filename is the validated media name.

Content-Length

Plaintext byte count, matching the media metadata.

X-Natter-Media-ID

Matches the requested temporary media handle.

Responses

200

Original inbound bytes with validated MIME and attachment disposition. Reading does not ACK the media.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner, verified selected number, customer permission, block or feature setting does not permit this operation.

404

not_found: no currently accessible resource in this business/environment.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Current key, owner, selected verified number, business/environment, contact window, block and feature permissions are checked again before decrypted reads. Outbound handles are private to the exact uploading key; any current key with Messaging & calls (messaging:manage, or an older key's converted messages:send) in the same business/environment can read an admitted inbound handle. A handle does not grant permission or renew the contact window. Send no request body or transfer encoding. Inbound only; acknowledges the hosted endpoint target and removes its private descriptor/handle. It does not acknowledge other recipients. Webhook HTTP 2xx and a successful download are separate from this explicit media ACK. After ACK, the handle is unavailable; a repeat can return 404.

No request body.

Responses

204

Inbound media acknowledged and private handle removed.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

Current key permission, owner, verified selected number, customer permission, block or feature setting does not permit this operation.

404

not_found: no currently accessible resource in this business/environment.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Returns at most eight current endpoint calls. Use this when no webhook is configured; not a call history. Listing authenticates the customer offers just like individual GET.

No request body.

Successful response

List current customer calls: response fields: calls[]

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Authenticates the native offer and records its native confirmation once before returning SDP. This does not answer the call. Your integration supplies its own WebRTC engine.

No request body.

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Apply offer_sdp to your WebRTC engine and send its generated answer here. Reuse the exact transaction, key and body after a lost response. A changed request under the same transaction conflicts; no Idempotency-Key header is used for call actions.

JSON request

JSON answer, at most 131,072 bytes; sdp itself at most 32,768 UTF-8 bytes.

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Returns at most ten signals. Always continue from next_after, including an empty page. No other query parameter is accepted; after must be canonical decimal 0..512 (no leading zero, sign, duplicate or percent encoding).

after (query, optional): Previous next_after cursor. Omit for the first page or send after=0; use the returned next_after even when signals is empty. Minimum: 0. Maximum: 512. Default: 0.

No request body.

Successful response

Read customer ICE candidates: response fields: signals[]

Read customer ICE candidates: response fields: signals[]: candidates[]

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Only after a successful answer. description_transaction must equal that answer transaction. At most 16 candidates; an empty array needs complete=true. Reuse the exact transaction/key/body after a lost response. At most 512 outgoing signaling frames per call.

JSON request

JSON ICE batch, at most 32,768 bytes. The normalized ICE payload must fit 16,384 UTF-8 bytes.

Complete request at most 32,768 bytes; the normalized ICE payload (description transaction, candidate fields and completion flag) must fit 16,384 UTF-8 bytes. No renegotiation; description_transaction must equal the successful answer transaction.

Send Business ICE candidates: request fields: candidates[]

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Send no body. Only the answered hosted endpoint can renew its 180-second lease. Send heartbeats before the returned expires_at; the customer lease and other call deadlines still apply.

No request body.

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Use decline or hangup. Exact same-key transaction retries remain supported after private call state is erased, subject to retained receipts and current authority. Stop your WebRTC engine and heartbeats when terminal.

JSON request

JSON end action, at most 1,024 bytes.

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Messaging & calls (messaging:manage)

Only customer-initiated calls are supported. Requires a current full-access key or a restricted key with Messaging & calls (messaging:manage, or an older key's converted calls:manage), the same business/environment and a current consenting customer relationship; voice_calls/video_calls must allow the authenticated offer. No Business call creation, waiting, renegotiation or format-2 offer support. Provides TURN credentials for your WebRTC engine, scoped by current call authority. Keep credentials on the call integration; do not log or persist them beyond expiry.

No request body.

Successful response

Responses

200

Current call state or committed action receipt.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

call_not_allowed or current Business authority: customer/contact/key/feature authority does not allow this action.

404

not_found: no currently accessible resource in this business/environment.

409

call_busy, call_changed or idempotency_conflict. Re-read current state; never change a body under an existing transaction.

410

call_ended: call is terminal or its current deadline expired. Stop local WebRTC and polling.

422

invalid_call_packet: native authenticated offer or signaling packet cannot be admitted.

429

call_limit: bounded call/signaling/TURN capacity reached.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Customers (customers:read)

Read only this business and environment using Billing (billing:read). Lists customers who have messaged the business. A customer must message first; you may reply for 4392 hours (183 days) after their last message unless they opt out or block the business. Opening a chat does not count and such customers are not listed. Returns the per-business user_ref used by webhooks. phone is the customer's verified number exactly when their last message event delivered it to you (every business receives it, D412) and that identity is still current; null for a customer who opted out or whose last message event carried no number (only a message accepted before Business API 0.9.0). can_message reflects the window and opt-out only; a paused business or unavailable number can still refuse a send. Never grants sending permission. Paging: results are pages of at most limit customers in the requested order (last message or first contact, newest first; ties by user_ref). To read every customer, request without a cursor, then repeat the same request with cursor set to next_cursor until next_cursor is null; keep every other parameter unchanged, because a cursor belongs to its order. A customer who messages while you page moves to the front of the last-message order, so use first_contact order (which never moves) or the export to read a fixed set. counts covers every listed customer in this environment regardless of filter or page; for a business with 10,000 or more customers they may be up to 60 seconds older than as_of (see counts_as_of). match_count is how many customers match the status and any search or date filter; with a search or date filter it stops counting at 10,000 and match_count_exact is then false.

status (query, optional): Only customers with this status. Default all. Default: "all".

sort (query, optional): last_inbound (default): most recent last message first. first_contact: most recent first contact first. Default: "last_inbound".

user_ref_prefix (query, optional): Only customers whose user_ref starts with this value (case-sensitive). Pass a whole user_ref for an exact match. Minimum characters: 1. Maximum characters: 96.

phone (query, optional): Only the customer whose verified number is this E.164 number; finds only a customer whose number is returned in phone. URL-encode the leading + as %2B, or omit it. See the full schema for validation rules.

last_inbound_from (query, optional): Only customers whose last message is at or after this RFC 3339 instant (microsecond precision at most). See the full schema for validation rules.

last_inbound_to (query, optional): Only customers whose last message is before this RFC 3339 instant. Must be after last_inbound_from. See the full schema for validation rules.

limit (query, optional): Page size, 1-200 in canonical decimal. Default 50. Minimum: 1. Maximum: 200. Default: 50.

cursor (query, optional): Opaque next_cursor from the previous page of the same request. Repeat every other parameter unchanged; a cursor from one sort order is refused for the other. Minimum characters: 1. Maximum characters: 256.

No request body.

Successful response

List customers you can message: response fields: counts

List customers you can message: response fields: contacts[]

List customers you can message: response fields: contacts[]: consent

Variant 1

Responses

200

Customers in this environment, with counts.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment (forbidden).

405

The method is not supported for this exact route.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.

Required permission: Customers (customers:read)

Every customer matching the filter, as one streamed text/csv file, using account:read. Takes the same status, sort, user_ref_prefix, phone and last_inbound_from/last_inbound_to parameters as the list, but no limit or cursor. The file is one consistent snapshot: every customer matching at X-Natter-As-Of appears exactly once with the status at that instant. Columns: user_ref, status, last_inbound_at, window_expires_at (empty for an opted-out customer), first_contact_at, phone (empty where the customer's last message event carried no number, and for an opted-out customer). Timestamps are RFC 3339 UTC. A business may start 10 exports per UTC hour across Live, Test, the API and the owner portal; the eleventh is 429 export_limit with Retry-After. A download can take up to ten minutes; if anything fails after the first byte the connection is closed before the end of the file, so treat an incomplete transfer as a failed export.

status (query, optional): Only customers with this status. Default all. Default: "all".

sort (query, optional): last_inbound (default): most recent last message first. first_contact: most recent first contact first. Default: "last_inbound".

user_ref_prefix (query, optional): Only customers whose user_ref starts with this value (case-sensitive). Pass a whole user_ref for an exact match. Minimum characters: 1. Maximum characters: 96.

phone (query, optional): Only the customer whose verified number is this E.164 number; finds only a customer whose number is returned in phone. URL-encode the leading + as %2B, or omit it. See the full schema for validation rules.

last_inbound_from (query, optional): Only customers whose last message is at or after this RFC 3339 instant (microsecond precision at most). See the full schema for validation rules.

last_inbound_to (query, optional): Only customers whose last message is before this RFC 3339 instant. Must be after last_inbound_from. See the full schema for validation rules.

No request body.

Successful response

Content-Type: text/csv. Header row user_ref,status,last_inbound_at,window_expires_at,first_contact_at,phone, then one row per customer.

Response headers

Content-Disposition

attachment; filename="natter-customers-<environment>-<YYYYMMDDTHHMMSSZ>.csv"

X-Natter-As-Of

The instant every row's status was computed at (RFC 3339).

Responses

200

The CSV file, streamed.

400

Invalid request body, header or noncanonical path. Oversized JSON also uses this response.

401

Missing, malformed, unknown or revoked Business API key.

403

The current key lacks the required permission or belongs to a different environment (forbidden).

405

The method is not supported for this exact route.

429

The business has started 10 exports in this UTC hour.

503

Candidate private HTTP resource controls: PostgreSQL validation and runtime publication are pending. The 16-request and 20-second limits below are not guarantees of the current deployed service. A dependency, transport deadline capability or required admission policy is unavailable, or the composed API's shared per-instance cap of 16 active requests is full. Local capacity refusal happens before authentication/body work and supplies Retry-After: 1. An early HTTP/1 refusal closes its connection without waiting for the remaining upload; HTTP/2 refusal is stream-scoped. This is not a tenant quota or paid throughput tier. Requests have an absolute 20-second read/write deadline, shortened by an earlier caller deadline; cancellation interrupts admitted I/O. A timeout does not prove that an action failed to commit: preserve the original send idempotency key/body on retry. Webhook PUT retry rotates its secret again. Distributed tenant/key/recipient rate limits, queue limits and fair scheduling remain commissioning gates. No success is implied by this error. temporarily_unavailable (D393): the key, scope, environment and number are allowed, but the business owner authority lease lapsed moments ago and has not been renewed yet (for example while a Natter or Masons Mail service restarts). Nothing was accepted. It always carries Retry-After: 5; retry the same request (a send with its original idempotency key and body) after that delay. A revoked or suspended owner, or a lease lapsed for more than two minutes, is refused with 403 forbidden instead and is not retryable.