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.
• 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.
• 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 available event types (see Webhook events reference for the full list):

• conversation.created, conversation.updated, conversation.resolved, conversation.reopened
• message.received, message.sent
• contact.created, contact.updated
• sla.warning, sla.breached
• assignment.changed
• tag.added, tag.removed

Limits

• Webhook count. Each tenant has a maxWebhooks limit (set per tenant). Trying to create more than that returns a 429.
• Webhooks must be enabled for your tenant. If they’re not, every /v1/webhooks call returns 403. Talk to your account team if you need them enabled.
• 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

• API Keys
• Webhook events reference
• Send an outbound message