Authentication

Visito’s developer API uses machine-to-machine credentials. Each key belongs to one tenant and includes explicit scopes that control what the integration can do.

M2M credentials are secrets. Store them only in server-side environment variables or a secrets manager. Never ship them in frontend, mobile, or embedded widget code.

Create an API Key

Open the Visito dashboard.
Go to Build → API Keys.
Click Create new API Key.
Choose a clear name, such as Order status sync or CRM automation.
Select only the scopes required by your integration.
Copy the key immediately and store it securely.

Authorization Header

Send the credential as a bearer token:

Authorization: Bearer visito_m2m_...

Scopes

Scopes are additive. A request succeeds only when the key has the scope required by that endpoint.

Scope	Allows
`channels:read`	List tenant channels and channel identifiers.
`conversations:read`	List conversations and read conversation detail.
`conversations:write`	Send replies into existing conversations.
`commerce:items:read`	List and inspect commerce catalog items.
`commerce:items:write`	Create, update, scope, and delete commerce catalog items.
`commerce:sales:read`	List and inspect commerce sales.
`tools:read`	List and inspect custom AI tools.
`tools:write`	Create, update, and delete custom AI tools.
`tools:execute`	Test custom AI tool execution.
`tools:logs:read`	Read custom AI tool execution logs.
`whatsapp_templates:read`	List WhatsApp templates for a channel.
`whatsapp_templates:write`	Create WhatsApp templates for Meta review.
`whatsapp_templates:send`	Send approved WhatsApp templates.

Example

curl https://platform-api.visitoai.com/m2m/v1/channels \
  -H "Authorization: Bearer $VISITO_M2M_API_KEY" \
  -H "Accept: application/json"

Idempotency

Send endpoints require an Idempotency-Key header. Use a stable value from your system, such as an order ID, payment ID, or CRM workflow run ID.

Idempotency-Key: order-confirmation-2423265220870

If your request is retried with the same key, Visito returns the original queued operation instead of creating a duplicate send.

Status Codes

Status	Meaning
`200`	Read request succeeded.
`201`	Resource was created.
`202`	Outbound work was accepted and queued.
`400`	Request body, query, or required header is invalid.
`401`	Authorization header is missing or invalid.
`403`	Credential is valid but missing the required scope.
`404`	Tenant-owned resource was not found.
`409`	The requested action conflicts with the current conversation or resource state.
`429`	A send safety limit was reached.
`502`	Visito could not queue or complete provider-facing work.
`503`	A required Visito dependency is temporarily unavailable.

Retry Policy

Retry GET requests after transient 429, 502, or 503 responses using exponential backoff and jitter.
Retry reply or template send requests only with the exact same body and the exact same Idempotency-Key.
Do not retry 400, 401, 403, 404, or 409 automatically.
If a 429 response includes error.details.retryAfterSeconds, wait at least that long.

Use a new idempotency key when the intended recipient, template, conversation, or message content changes.

Build With Visito

AI Coding Assistants

Create an API Key

Authorization Header

Scopes

Example

Idempotency

Status Codes

Retry Policy

​Create an API Key

​Authorization Header

​Scopes

​Example

​Idempotency

​Status Codes

​Retry Policy

Create an API Key

Authorization Header

Scopes

Example

Idempotency

Status Codes

Retry Policy