Skip to main content
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

  1. Open the Visito dashboard.
  2. Open Developers → API Keys.
  3. Click Create new API Key.
  4. Choose a clear name, such as Order status sync or CRM automation.
  5. Select only the scopes required by your integration.
  6. Copy the key immediately and store it securely.

Authorization Header

Send the credential as a bearer token:

Scopes

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

Example

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.
If your request is retried with the same key, Visito returns the original queued operation instead of creating a duplicate send.

Status Codes

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.

Additional scopes

  • conversations:assignment:read
  • conversations:assignment:write
  • conversations:handoffs:write
  • conversations:policy:write
  • crm:sales:read
  • crm:sales:write
  • knowledge:read
  • knowledge:write
  • messages:read
  • properties:read
  • reporting:read
  • webhooks:read
  • webhooks:write
Write scopes do not imply read. Webhook subscriptions also require the corresponding resource read scope. Existing keys are unchanged. ops:handoffs:create does not authorize the separate Ops API.

Action management permissions

These permissions are independent. Configuration access never implies execution or diagnostics. Existing keys and OAuth grants remain unchanged; a refresh token cannot add scopes. Migration details.

Guest AI configuration permissions

  • ai_settings:read: current guest personality/raw runtime inputs, photo limit and escalation policy.
  • ai_settings:write: versioned updates to those existing settings.
These scopes require explicit consent and do not imply conversation traces, Action parameters/inspection, channel control or scheduled-message permissions. Existing grants remain unchanged. See AI settings.

Separate channel connection and management access

channels:read reads channels and connection attempts. channels:write retains only the existing versioned automatic-reply operation. New channels:connect:write creates temporary human-completed connection links, and new channels:manage:write manages activation/configuration, requested disconnects and supported provider maintenance. New operations recheck current admin ownership. Existing API keys and OAuth grants retain their exact scopes. Grant additional permissions explicitly, without widening old credentials. See channel contract and recovery.

Tickets and escalations

tickets:read discovers both types; tickets:write manages general tickets. conversations:handoffs:create initiates escalation; escalation management retains conversations:handoffs:write and assignment retains conversations:assignment:write. Context reads and sending permissions remain separate. Existing credentials and OAuth grants retain their exact scopes; explicitly grant new access. See the contract and agent workflow.

Commerce access is explicit

Existing API keys and OAuth grants retain their scopes. Request an explicit new grant for either Commerce mutation scope, together with sales read. Ticket read/write alone cannot mutate a purchase. Built-in Agent approvals remain required; the credential/grant is the audit identity. See the complete Tickets and escalation operation matrix, MCP workflow and Commerce commands with sourceVersion.