How to create a custom channel

A custom channel connects a system you already run — your order system, a review site, a Zapier zap, anything that can send and receive HTTP — to Atender. Atender gives the channel an ingress URL your system POSTs messages to, and a signing secret Atender uses on everything it sends out to you. Every reply an agent sends goes back out over your webhook, so there’s no email or phone fallback for a custom channel — your system is the only place a reply can land.

This is different from the general-purpose REST API: a custom channel is a configured, named integration with its own routing, delivery log, and health state, set up entirely from Settings.

Before you start

You’ll need:

• Admin access to the tenant.
• A webhook URL on your side that Atender can POST inbound events to, and that you’re prepared to receive deliveries at.
• A plan for where conversations from this channel should land — a default team, and optionally a default agent stack.

A tenant API key with the channels:write scope. This is not optional extra credit: the ingress URL is a route on the v1 API (POST /api/v1/channels/<id>/messages), and it authenticates with Authorization: Bearer <api key> like every other v1 route. Add channels:read if your integration also lists channels.

Add a custom channel

1. Go to Settings → Custom channel.
2. If this is your first custom channel, you’ll see an empty state — click Add channel. If you already have one or more, use the same action to add another.
3. Give it a name — something that identifies the system on the other end (for example, “Order system” or “Review site”). This name is what agents see as the channel on the conversation.
4. Enter the webhook URL — the endpoint on your system that Atender will call for outbound events (replies, and any other channel events your integration handles).
5. Save. Atender creates the channel and returns two things you’ll only see once:
   The secret for this channel.
   The ingress URL — the Atender endpoint your system POSTs inbound messages to.

Copy the secret now. It’s shown once, at creation. Atender doesn’t store it in a way it can redisplay later — if you lose it, you’ll need to rotate it and update your system with the new value.

What the ingress URL and secret are for

• Ingress URL — a per-channel Atender endpoint, unique to this custom channel. Your system POSTs to this URL whenever a new message should become a conversation (or a new message on an existing conversation) in Atender.
• Secret — the signing secret for everything Atender sends to you. Each outbound delivery (a reply, a test event) carries a signature computed with it, and your endpoint should verify that signature before trusting the call. It does not authenticate your inbound POSTs: those carry your tenant API key instead, as the sample curl on the channel shows.

Both values live on the channel’s detail view if you need to copy the ingress URL again later — only the secret itself is one-time.

Assign a default team and agent stack

A custom channel can route to a default team, and optionally a default agent stack, so conversations coming in over that webhook land somewhere sensible without an agent having to triage them first. Both are optional — the team picker includes No team.

1. Open the custom channel from Settings → Custom channel.
2. Pick a default team from the list of teams on your tenant, or leave it on No team.
3. Optionally pick a default agent stack to handle the conversation before or alongside a human agent.

Auto-resolve on inactivity

A custom channel can be configured to auto-resolve a conversation after a period of inactivity, the same idea as inactivity handling on other channels. Turn on auto-resolve on inactivity and set the number of minutes of silence after which an open conversation on this channel should resolve itself.

Send a test event

Before pointing real traffic at the channel, use the test-send action on the channel’s detail view to fire a sample event at your configured webhook URL. This confirms your endpoint is reachable and responding before your order system or Zapier zap depends on it.

View and resend failed deliveries

Replies and other outbound channel events are logged as deliveries. A test send is not: it reports its result to you on the spot and writes no delivery row, and it doesn’t count towards the channel’s health either. From the channel’s detail view:

• Open the delivery log to see each attempt: the event type, attempt number, status (success or failed), the response status code and response time, and, for failures, the error message.
• Click into a delivery to see the full outgoing payload and the response body your system returned.
• If a delivery failed, use resend to send it again. Atender rebuilds the request from the stored message, so the envelope carries a new event id — deduplicate on the message id inside it, not on the event id. The retry is recorded as its own delivery row and never downgrades an already-sent message.

Rotate the secret

If the secret is compromised, or you’ve lost it and can’t retrieve it (it’s never shown again after creation), rotate it from the channel’s detail view. Rotating issues a new secret — shown once, the same as at creation — and immediately invalidates the old one. Update the verification on your receiving system right away, since deliveries after the rotation are signed with the new secret and will fail your check if it still expects the old one. Your inbound calls are unaffected — those authenticate with your API key, not this secret.

Auto-disable after repeated failures

If Atender’s calls to your webhook fail repeatedly in a row, the channel auto-disables itself rather than continuing to retry indefinitely. A disabled channel shows the reason it was disabled and stops attempting new deliveries until you re-enable it — typically after you’ve fixed whatever was rejecting the calls on your side (an expired endpoint, a broken auth check, a deploy that changed the response shape). Check the delivery log first; the failed entries there usually show exactly what your endpoint returned.

Replies only flow back over the webhook

There’s no email or phone fallback for a custom channel. When an agent replies on a custom-channel conversation, that reply is sent to your webhook URL and nowhere else — Atender does not fall back to the contact’s email or phone number even if one is on file. The one case where a reply is not delivered at all is a conversation that arrived through an inbound endpoint marked no reply: the agent is told so, and the reply is not sent anywhere. Your system is responsible for getting that reply in front of the end user (posting it to your order system’s message thread, your review platform, etc.). If your webhook is down or rejecting calls, replies won’t reach anyone until it’s fixed — which is also why the delivery log and auto-disable behavior exist, so a broken endpoint doesn’t silently swallow replies.