Channelsadvanced

REST API integration

Atender's v1 REST API lets you create conversations programmatically and subscribe to webhook events for outbound notifications. Authenticated with tenant API keys — no separate channel UI to configure.

6 min read

REST API integration

Atender exposes a v1 REST API that lets you push conversations in from your own systems and subscribe to event webhooks that fire when conversations change. This is how you build a custom integration when none of the built-in channels (Email, Web Chat, Voice, SMS, WhatsApp, Messenger, Amazon) fit your use case.

What you can do with the API

  • Create conversations with any contact, on any channel, tagged with custom metadata. Useful when you have a touchpoint that lives outside Atender — a custom in-app chat, a marketplace inbox, a legacy ticketing tool — and you want the conversation in Atender’s inbox.
  • Subscribe to event webhooks. Atender will POST a payload to your URL whenever something happens — a new message arrives, a conversation is resolved, an SLA is breached, a tag is added.
  • Read conversation, contact, and message data from your own systems for reporting, syncing, or building UI.
  • Read Atender Supervisor analysis programmatically. Owners with access can pull the current digest, historical runs, ranked findings, and the evidence conversations behind those findings.
  • Authenticate with long-lived tenant API keys (sa_live_* for production, sa_test_* for testing). No JWT juggling, no OAuth.

How this differs from a built-in channel

Atender’s built-in channels (Email, Web Chat, etc.) have settings pages, dedicated routing, and tenant-managed configuration. The API is different:

  • No channel-specific settings UI. You don’t configure “the API channel” — you generate an API key, write code against the v1 endpoints, and that’s the integration.
  • The “channel” on each API-created conversation is one you specify. When you push a conversation via POST /v1/conversations/outbound, you pass a channel field. It can be any of the standard channels (email is the default), but you control it from the client.
  • Webhook subscriptions are managed via API, not via a settings page. You create, update, list, and delete subscriptions with HTTP calls against /v1/webhooks.

If you came here looking for “the API Channel” as a configurable channel like Email or Web Chat, you won’t find it — that’s not what this is. This is a programmatic interface for tenants who write code.

What you’ll need

  • A tenant API key with appropriate scopes. Generate one in Settings → API Keys. Keys never expire — rotate when needed from the same screen.
  • The right scopes for the operations you’ll perform:
  • conversations:write — create or modify conversations programmatically.
  • conversations:read — read conversation data.
  • webhooks:read and webhooks:write — list and manage your webhook subscriptions.
  • supervisor:read — read Atender Supervisor data, including digests, historical runs, ranked findings, and evidence conversations. This scope is read-only, requires Supervisor access, and only works when the tenant has opted into the full self-learning/Supervisor data flow.
  • Other scopes (contacts:read/write, channels:write, etc.) for the resources you’ll touch.
  • A server that can make HTTP requests and (if subscribing to webhooks) receive them at a public URL.

Authentication

Every request to /v1/* carries the API key as a Bearer token:

Authorization: Bearer sa_live_xxxxxxxxxxxxxxxxxxxxxxxx

The key encodes your tenant, so endpoint URLs do not include a tenant ID — Atender resolves it from the key.

Webhooks

Webhooks are the inbound half of the integration. Subscribe to one or more event types, give Atender a URL, and your server will receive a signed POST request whenever those events fire.

Today’s emitted event types (see Webhook events reference for the full list):

  • conversation.created, conversation.resolved, conversation.reopened, conversation.commented
  • message.received, message.sent
  • sla.warning, sla.breached
  • kb.article.created, kb.article.updated, kb.article.deleted
  • handbook.procedure.created, handbook.procedure.updated, handbook.procedure.deleted

KB and Handbook events are intended for sync consumers: the webhook payload identifies what changed, and your consumer should refetch the full content from the relevant API.

Webhook subscription validation may still accept older enum values for compatibility, but new integrations should rely on the emitted events advertised by GET /v1/webhooks.

Limits

  • Webhook count. Each tenant has a maxWebhooks limit (5 by default, adjustable per tenant). Trying to create more than that returns 403 LIMIT_EXCEEDED.
  • Webhook scopes are required. API keys need webhooks:read to list or read webhook subscriptions, and webhooks:write to create, update, delete, or rotate webhook secrets.
  • External references must be unique per tenant. Each conversation you push via POST /v1/conversations/outbound carries an externalReference you supply. Pushing twice with the same reference returns 409 — use this to safely retry on network errors.

Where to start

  1. Generate an API key with conversations:write and webhooks:read + webhooks:write in Settings → API Keys.
  2. Send an outbound message — create your first programmatic conversation.
  3. Subscribe to webhook events — get notified when things change.

See also

Tags

Getting StartedConcept
Back to Channels