Channels API
Configure outbound and inbound messaging, manage send/receive addresses and per-address inbound config, queue messages, and audit activity. Each channel config is rooted in a zero-trust channel zone, so access is governed by per-channel and per-address grants. Conversations consumes the inbound-config snapshot to create or continue one participant thread, request exactly one Workflows item when a handler is set, and add configured subscribers. Handler and subscriber changes publish `channels.address.inbound_config.updated`.
/api/v1/channelsAutomation triggers: view every Channels event, payload field, and predicate.
Configs
Create and manage email setups per company. Platform Domain uses a platform-owned domain immediately; Custom Domain verifies a customer-owned domain. Both create virtual/routed addresses, not mailboxes. Connected Mailbox connects real Gmail or Microsoft 365 mailboxes through the Connected mailboxes endpoints. Each config roots a zero-trust channel zone at org/{company_id}/channel/{config_id}.
/api/v1/channels/configsCreate Config
Register a Platform Domain or Custom Domain configuration. Connected mailboxes are created with Create Connected Mailbox instead; this endpoint answers 400 `connectedMailboxUseConnectEndpoint` for them. The API uses integration_type with no aliases for historical provider values.
Bearer token required. x-company-id header required.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Display name (1–200 characters) |
integration_type* | "platform-domain" | "custom-domain" | "connected-mailbox" | Email setup model. connected-mailbox is rejected here; use Create Connected Mailbox. |
domain | string | Customer-owned domain for custom-domain (3–253 characters). Omit for platform-domain. |
channel_type | string | Channel implementation slugDefault: email |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Config ID |
company_id* | string | Owning company ID |
channel_type* | string | Channel type slug |
integration_type* | "platform-domain" | "custom-domain" | "connected-mailbox" | "business-account" | Provider-neutral setup model for email and WhatsApp Business accounts. |
name* | string | Display name |
domain* | string | null | Configured domain |
status* | string | Lifecycle status (e.g. pending_dns, verifying, verified) |
setup_details* | object | null | Safe, channel-specific setup metadata. Email details include kind=email plus DNS records or the Platform Domain mail namespace; WhatsApp details expose operational identifiers but never secrets; Embedded Signup details add token_expires_at, needs_reauth / needs_reauth_reason (reconnect with Facebook) and token_checked_at. |
inbound_enabled* | boolean | Whether inbound handling is enabled for this config |
created_at* | string | Creation time (ISO 8601) |
updated_at* | string | Last update time (ISO 8601) |
capabilities | object | What the calling principal may do with this config |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}" \
-H "Content-Type: application/json" \
-d '{
"name": "Primary email",
"integration_type": "custom-domain",
"domain": "mail.example.com",
"channel_type": "email"
}'Response
201 Created{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "email",
"integration_type": "custom-domain",
"name": "Primary email",
"domain": "mail.example.com",
"status": "pending_dns",
"setup_details": {
"kind": "email",
"dns_records": [
{
"type": "TXT",
"name": "resend._domainkey.mail.example.com",
"value": "p=MIGfMA0GCS..."
}
]
},
"inbound_enabled": false,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-01T12:00:00Z",
"capabilities": {
"can_list_addresses": true,
"can_create_address": true,
"can_delete_address": true,
"can_send": true,
"manage_addresses": true,
"manage_settings": true,
"manage_security": true,
"view_activity": true
}
}/api/v1/channels/configsList Configs
Return all channel configs visible to the caller for their company.
Bearer token required. x-company-id header required.
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | ConfigResponse[] | Configs ordered by created_at descending |
curl https://platform.ergondata.ai/api/v1/channels/configs \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}"Response
200 OK[
{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "email",
"integration_type": "custom-domain",
"name": "Primary email",
"domain": "mail.example.com",
"status": "verified",
"setup_details": { "kind": "email", "dns_records": [] },
"inbound_enabled": true,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-02T09:15:00Z",
"capabilities": { "can_send": true, "manage_settings": true }
}
]/api/v1/channels/configs/{config_id}Get Config
Fetch one config by ID. Custom Domain may refresh DNS records and verification status; Platform Domain is already verified.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "email",
"integration_type": "custom-domain",
"name": "Primary email",
"domain": "mail.example.com",
"status": "verified",
"setup_details": {
"kind": "email",
"dns_records": []
},
"inbound_enabled": true,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-02T09:15:00Z",
"capabilities": { "can_send": true, "manage_settings": true }
}/api/v1/channels/configs/{config_id}Update Config
Update the display name for a config.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New display name |
curl -X PATCH https://platform.ergondata.ai/api/v1/channels/configs/{config_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Primary email (updated)"}'Response
200 OK{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "email",
"integration_type": "custom-domain",
"name": "Primary email (updated)",
"domain": "mail.example.com",
"status": "verified",
"setup_details": { "kind": "email", "dns_records": [] },
"inbound_enabled": true,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-03T16:00:00Z"
}/api/v1/channels/configs/{config_id}/verifyVerify Config
Verify DNS for a Custom Domain and move it toward verified. Platform Domain requires no DNS verification.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/verify \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "email",
"integration_type": "custom-domain",
"name": "Primary email",
"domain": "mail.example.com",
"status": "verifying",
"setup_details": { "kind": "email", "dns_records": [] },
"inbound_enabled": true,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-03T14:22:00Z"
}/api/v1/channels/configs/{config_id}/whatsapp/phone-numbersDiscover WhatsApp Phone Numbers
List phone numbers directly from the config's Meta WABA, including verification and quality state and whether each number is already connected.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Ready WhatsApp business-account config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | WhatsAppPhoneNumberCandidate[] | Meta-derived phone IDs, normalized numbers, verification/quality state, and local connected state |
total* | integer | Number of candidates returned by Meta |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/phone-numbers \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"phone_number_id": "123456789012345",
"business_phone_number": "+5511914409811",
"display_name": "Brazil support",
"verification_status": "VERIFIED",
"quality_rating": "GREEN",
"platform_type": "CLOUD_API",
"operational_status": "CONNECTED",
"connected": false,
"connected_address_id": null
}
],
"total": 1
}/api/v1/channels/configs/{config_id}/whatsapp/phone-numbersAdd WhatsApp Phone Number
Add one verified number discovered under the existing WABA. Channels re-fetches the number from Meta and derives every address field; the generic address endpoint cannot create WhatsApp numbers.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Ready WhatsApp business-account config ID |
Request Body
| Name | Type | Description |
|---|---|---|
phone_number_id* | string | Meta phone-number ID returned by the discovery endpoint |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/phone-numbers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"phone_number_id":"123456789012345"}'Response
201 Created{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "+5511914409811",
"display_name": "Brazil support",
"direction": "both",
"status": "active",
"channel_type": "whatsapp",
"provider_phone_number_id": "123456789012345",
"operational_status": "connected",
"quality_rating": "GREEN"
}/api/v1/channels/configs/whatsapp/embedded-signupGet WhatsApp Embedded Signup Settings
Public settings the browser needs to open Meta's Embedded Signup popup (Facebook JS SDK, Embedded Signup v4): the platform Meta app ID, the Facebook Login for Business configuration ID, and the Graph version. `enabled` is false when the deployment has no Embedded Signup configuration; secrets are never returned.
Bearer token required.
curl https://platform.ergondata.ai/api/v1/channels/configs/whatsapp/embedded-signup \
-H "Authorization: Bearer {token}"Response
200 OK{
"enabled": true,
"app_id": "1234567890",
"config_id": "9876543210",
"graph_version": "v27.0"
}/api/v1/channels/configs/whatsapp/embedded-signupConnect WhatsApp (Embedded Signup)
Finish Meta's Embedded Signup popup. Send the code `FB.login` returned at once (it is single use and expires after about 30 seconds) with the `WA_EMBEDDED_SIGNUP` session info. Channels exchanges the code for the tenant's business token, checks it belongs to the platform app, stores it and a generated two-step PIN in a Vault namespace managed by the config, subscribes the platform app to the WABA, and registers the number (skipped for coexistence). A config whose setup failed part-way is resumed by signing up again with the same WABA. To reconnect a ready channel (its token was refused, revoked or is about to expire), send `config_id`: the new token replaces the old one in the same Vault credential, the app is re-subscribed and `needs_reauth` is cleared, with no new channel and no number registration; this needs `channels:channels:manage` on that channel. Requires `channels:channels:create` and `vault:namespaces:create`. Browser-only: not an agent tool.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Channel name |
code* | string | Exchangeable code from `FB.login` (response_type `code`) |
waba_id | string | WABA ID from the session event; when omitted the single WABA granted to the token is used |
phone_number_id | string | Phone number ID from the session event; when omitted a WABA with exactly one number connects that number |
business_id | string | Customer business portfolio ID from the session event |
event | string | Session event type; `FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING` keeps the number on the WhatsApp Business app (coexistence) and skips Cloud API registration |
config_id | uuid | Reconnect this existing Embedded Signup channel instead of creating one. The popup must grant the channel's own WABA (409 `whatsapp_reauth_waba_mismatch` otherwise); manual channels answer 409 `whatsapp_reauth_unsupported` |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/whatsapp/embedded-signup \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "WhatsApp support", "code": "{code}", "waba_id": "102290129340398", "phone_number_id": "106540352242922", "event": "FINISH"}'Response
201 Created{
"config": {
"id": "8f2c1a00-1111-4222-8333-444455556666",
"channel_type": "whatsapp",
"integration_type": "business-account",
"name": "WhatsApp support",
"status": "verified",
"setup_details": {
"kind": "whatsapp",
"onboarding_method": "embedded-signup",
"webhook_mode": "app",
"provisioning_status": "ready",
"token_expires_at": null,
"token_never_expires": true
}
},
"address_id": "a1b2c3d4-0000-4000-8000-000000000001",
"phone_number_id": "106540352242922",
"next_step": "none"
}/api/v1/channels/configs/{config_id}/whatsapp/credentials/connectConnect WhatsApp Credentials
Re-run WhatsApp provisioning for the config: connect the Vault credential consumer for the channel principal, validate the Meta credentials, and refresh the config status. Use after granting or rotating the Vault credentials referenced by the config. For an Embedded Signup config this retries the remaining setup steps with the stored token.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/credentials/connect \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "8f2c1a00-1111-4222-8333-444455556666",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_type": "whatsapp",
"integration_type": "whatsapp-business-account",
"name": "WhatsApp support",
"status": "verified",
"setup_details": { "kind": "whatsapp", "provisioning_status": "ready" },
"inbound_enabled": true,
"created_at": "2026-04-01T12:00:00Z",
"updated_at": "2026-04-03T14:22:00Z"
}/api/v1/channels/configs/{config_id}Delete Config
Remove the config and integration-owned domain state. The account-level Resend webhook is deployment configuration and is never deleted by config lifecycle.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentConnected mailboxes
Connect real Gmail and Microsoft 365 mailboxes through the provider's API. The channel stores its secrets in its own Vault namespace and never returns them. Every connected mailbox becomes an address: sending goes out from the mailbox, receiving ingests new mail into Conversations, and agents read and organize it with the Mailbox endpoints. These endpoints are browser and API only, not agent tools.
/api/v1/channels/configs/connected-mailbox/providersList Mailbox Providers
Mailbox providers this deployment can connect, with their connection methods and connect-form fields. The list is empty until a provider is available. Requires `channels:channels:create`.
Bearer token required. x-company-id header required.
Response Fields
| Name | Type | Description |
|---|---|---|
providers* | object[] | Available providers |
curl https://platform.ergondata.ai/api/v1/channels/configs/connected-mailbox/providers \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}"Response
200 OK{
"providers": [
{
"name": "microsoft",
"label": "Microsoft 365",
"supports_webhooks": true,
"auth_methods": [
{
"method": "app_registration",
"credential_scope": "channel",
"browser_consent": false,
"fields": [
{ "key": "tenant_id", "kind": "text", "label": "Tenant ID", "required": true },
{ "key": "client_id", "kind": "text", "label": "Client ID", "required": true },
{ "key": "client_secret", "kind": "secret", "label": "Client secret", "required": true }
]
}
]
}
]
}/api/v1/channels/configs/connected-mailboxCreate Connected Mailbox
Create a connected-mailbox channel. The connect-form secrets are stored in a Vault namespace the channel manages. For service_account and app_registration the listed mailboxes are verified at once and next_step is `ready`. For user_oauth a person signs in at the provider: start the Vault OAuth flow on oauth_credential_id, then call Finalize Connected Mailbox. Errors use `mailbox*` codes with params. Requires `channels:channels:create` and `vault:namespaces:create`.
Bearer token required. x-company-id header required.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Channel name |
provider* | "gmail" | "microsoft" | Mailbox provider |
auth_method* | "user_oauth" | "service_account" | "app_registration" | How the channel reaches the mailboxes |
credentials | object | Connect-form values by field key; secrets are never returned |
access | ("read" | "organize" | "send")[] | What the channel may do in the mailboxes: read, organize (mark as read, archive, labels) and send. Defaults to all three |
mailboxes | object[] | Mailboxes to connect; required unless auth_method is user_oauth |
account_direction | "send" | "receive" | "both" | user_oauth only: direction of the signed-in account's mailboxDefault: both |
Response Fields
| Name | Type | Description |
|---|---|---|
config* | object | The channel config |
next_step* | "authorize" | "ready" | authorize: start the provider sign-in for oauth_credential_id, then call finalize. ready: the mailboxes were verified |
oauth_credential_id | string | null | The Vault credential the provider sign-in connects (user_oauth) |
mailboxes | object[] | The addresses created |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/connected-mailbox \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"name": "Support mailboxes", "provider": "microsoft", "auth_method": "app_registration", "credentials": {"tenant_id": "{tenant_id}", "client_id": "{client_id}", "client_secret": "{client_secret}"}, "mailboxes": [{"address": "support@example.com", "direction": "both"}]}'Response
201 Created{
"config": {
"id": "8f2c1a00-1111-4222-8333-444455556666",
"channel_type": "email",
"integration_type": "connected-mailbox",
"name": "Support mailboxes",
"status": "verified",
"setup_details": {
"kind": "email",
"mailbox": {
"provider": "microsoft",
"auth_method": "app_registration",
"credential_scope": "channel",
"access": ["read", "organize", "send"],
"status": "connected",
"webhooks_enabled": true,
"webhook_url": "https://platform.ergondata.ai/api/v1/channels/webhooks/connected-mailbox/microsoft",
"secret_fields": [
{ "key": "client_secret", "kind": "secret", "label": "Client secret", "required": true }
]
}
}
},
"next_step": "ready",
"oauth_credential_id": null,
"mailboxes": [
{ "id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00", "address": "support@example.com", "direction": "both", "receive_enabled": false }
]
}/api/v1/channels/configs/{config_id}/connected-mailbox/finalizeFinalize Connected Mailbox
After the person signs in at the provider (user_oauth), verify the signed-in account and add its mailbox. Requires `channels:channels:manage`.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Connected-mailbox config ID |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/connected-mailbox/finalize \
-H "Authorization: Bearer {token}"Response
200 OK{
"config": { "id": "8f2c1a00-1111-4222-8333-444455556666", "status": "verified" },
"next_step": "ready",
"oauth_credential_id": "c2a1b3d4-0000-4000-8000-000000000002",
"mailboxes": [
{ "id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00", "address": "ana@example.com", "direction": "both" }
]
}/api/v1/channels/configs/{config_id}/connected-mailbox/mailboxesAdd Connected Mailbox
Add and verify one more mailbox on a service_account or app_registration channel. When the method has one credential per mailbox, send the connect-form secrets again; the channel's `setup_details.mailbox.secret_fields` lists them. Requires `channels:addresses:create`.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Connected-mailbox config ID |
Request Body
| Name | Type | Description |
|---|---|---|
address* | string | Mailbox email address |
direction | "send" | "receive" | "both" | receive reads it, send sends from it, both does bothDefault: both |
display_name | string | null | Display name |
credentials | object | Only for credential_scope mailbox: the connect-form secrets, such as the service account key |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/connected-mailbox/mailboxes \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"address": "billing@example.com", "direction": "receive"}'Response
201 Created{
"id": "b2e3f4a5-6677-8899-aabb-ccddeeff0011",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "billing@example.com",
"direction": "receive",
"status": "active",
"receive_enabled": false
}/api/v1/channels/configs/{config_id}/connected-mailbox/credentialsReplace Connected Mailbox Secret
Replace the stored client secret or key; the other connect-form values are kept. The channel's `setup_details.mailbox.secret_fields` lists the fields to send. Call Reconnect Connected Mailbox afterwards to check access again. Requires `channels:channels:manage`.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Connected-mailbox config ID |
Request Body
| Name | Type | Description |
|---|---|---|
credentials* | object | The new secret values by field key |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/connected-mailbox/credentials \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"credentials": {"client_secret": "{client_secret}"}}'Response
200 OK{
"config": { "id": "8f2c1a00-1111-4222-8333-444455556666", "status": "verified" },
"next_step": "ready",
"oauth_credential_id": null,
"mailboxes": []
}/api/v1/channels/configs/{config_id}/connected-mailbox/reconnectReconnect Connected Mailbox
Check access to the mailboxes again and resume receiving. For user_oauth, sign in again to setup_details.mailbox.sign_in_credential_id first; signing in as a different account is refused (409 `mailboxReconnectDifferentAccount`). Requires `channels:channels:manage`.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Connected-mailbox config ID |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/connected-mailbox/reconnect \
-H "Authorization: Bearer {token}"Response
200 OK{
"config": { "id": "8f2c1a00-1111-4222-8333-444455556666", "status": "verified" },
"next_step": "ready",
"oauth_credential_id": null,
"mailboxes": []
}Addresses
Manage send/receive addresses under a config, and list every address visible to the current company.
/api/v1/channels/addressesList Company Addresses
List channel addresses for the caller's company. Optionally filter by channel type, direction, or only sendable verified addresses.
Bearer token required. x-company-id header required.
Query Parameters
| Name | Type | Description |
|---|---|---|
channel_type | string | Filter by config channel type (e.g. email) |
direction | string | Filter by direction: send, receive, or both |
sendable | boolean | When true, only active send/both addresses on verified configsDefault: false |
authorized_to_send | boolean | When true, filter rows by the caller's channels:addresses:send permission instead of channels:addresses:viewDefault: false |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | AddressResponse[] | id, channel_config_id, address, display_name, direction, status, channel_type, channel_name, timestamps |
curl "https://platform.ergondata.ai/api/v1/channels/addresses?sendable=true&channel_type=email" \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}"Response
200 OK[
{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "hello@mail.example.com",
"display_name": "Support",
"direction": "both",
"status": "active",
"channel_type": "email",
"channel_name": "Primary email",
"created_at": "2026-04-02T10:00:00Z",
"updated_at": "2026-04-02T10:00:00Z"
}
]/api/v1/channels/configs/{config_id}/addressesCreate Address
Add an email address under a config. The address must use the config domain. Receive/both addresses require inbound to be available and may enable inbound on the config. WhatsApp numbers must use the Meta-backed discovery and add endpoints.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Request Body
| Name | Type | Description |
|---|---|---|
address* | string | Full address, e.g. support@mail.example.com (3–320 characters) |
display_name | string | null | Optional display name for From headers |
direction | string | send, receive, or bothDefault: send |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"address": "support@mail.example.com",
"display_name": "Support",
"direction": "send"
}'Response
201 Created{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "support@mail.example.com",
"display_name": "Support",
"direction": "send",
"status": "active",
"channel_type": null,
"channel_name": null,
"created_at": "2026-04-02T10:00:00Z",
"updated_at": "2026-04-02T10:00:00Z"
}/api/v1/channels/configs/{config_id}/addressesList Addresses
List all addresses belonging to a single channel config.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "support@mail.example.com",
"display_name": "Support",
"direction": "send",
"status": "active",
"channel_type": "email",
"channel_name": "Primary email",
"created_at": "2026-04-02T10:00:00Z",
"updated_at": "2026-04-02T10:00:00Z"
}
]/api/v1/channels/addresses/whatsapp/outboundList WhatsApp Outbound Addresses
List WhatsApp phone numbers the caller can send from: active send/both addresses on verified WhatsApp configs, filtered by the caller's send permission. Prefer this over the generic address list when starting or continuing WhatsApp outreach.
Bearer token required. Requires the X-Company-Id header.
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Page size (default 100, max 200) |
offset | integer | Pagination offset (default 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | AddressResponse[] | WhatsApp addresses the caller may send from |
total* | integer | Total matching addresses |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/whatsapp/outbound?limit=50" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{
"items": [
{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "+5511914409811",
"display_name": "Brazil support",
"direction": "both",
"status": "active",
"channel_type": "whatsapp"
}
],
"total": 1
}/api/v1/channels/addresses/{address_id}/whatsapp/send-optionsGet WhatsApp Send Options
Return what may be sent from this WhatsApp address to one recipient right now: whether the 24-hour customer-service window is open (free-form allowed), when the session expires, and the approved utility templates enabled for the address.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | WhatsApp address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
to* | string | Recipient phone number in E.164 format |
limit | integer | Template page size (default 100, max 200) |
offset | integer | Template pagination offset (default 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
free_form_allowed* | boolean | True when the 24-hour session window with this recipient is open |
session_expires_at* | string (ISO 8601) | null | When the open session window closes, if one exists |
items* | WhatsAppTemplateResponse[] | Approved, active utility templates enabled for this address |
total* | integer | Total templates available to this address |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/whatsapp/send-options?to=%2B5511999999999" \
-H "Authorization: Bearer {token}"Response
200 OK{
"free_form_allowed": false,
"session_expires_at": null,
"items": [
{
"id": "77e3a9b2-1234-4cde-9f00-aabbccddeeff",
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"status": "APPROVED",
"rejected_reason": null,
"components": [],
"is_active": true,
"allowed_address_ids": ["a1d2e3f4-5566-7788-99aa-bbccddeeff00"],
"last_synced_at": "2026-04-03T14:22:00Z"
}
],
"total": 1
}/api/v1/channels/addresses/{address_id}/whatsapp/contacts/{wa_id}/marketing-policyUpdate WhatsApp Marketing Policy
Record a marketing opt-out (or opt-in) for one WhatsApp contact on this address. Opted-out contacts are excluded from marketing template sends while transactional traffic continues.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | WhatsApp address ID |
wa_id* | string | WhatsApp contact ID (phone-derived) |
Request Body
| Name | Type | Description |
|---|---|---|
opted_out* | boolean | True to opt the contact out of marketing sends |
Response Fields
| Name | Type | Description |
|---|---|---|
wa_id* | string | WhatsApp contact ID |
opted_out* | boolean | Current marketing opt-out state |
updated_at* | string (ISO 8601) | When the policy was last changed |
curl -X PATCH https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/whatsapp/contacts/{wa_id}/marketing-policy \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"opted_out":true}'Response
200 OK{
"wa_id": "5511999999999",
"opted_out": true,
"updated_at": "2026-04-03T14:22:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}Update Address
Update the display name, direction, or status slug of an address. For a connected mailbox, also turn receiving on or off; a direction the channel's access does not cover is refused (400 `mailboxAccessMissingRead` / `mailboxAccessMissingSend`).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Request Body
| Name | Type | Description |
|---|---|---|
display_name | string | null | New display name |
direction | string | null | send, receive, or both |
status | string | null | Address status slug (e.g. active, disabled) |
receive_enabled | boolean | null | Connected mailbox only: ingest new mail arriving in this mailbox. Turning it on starts from now; older mail is never ingested. |
curl -X PATCH https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"direction": "both"}'Response
200 OK{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "support@mail.example.com",
"display_name": "Support",
"direction": "both",
"status": "active",
"channel_type": null,
"channel_name": null,
"created_at": "2026-04-02T10:00:00Z",
"updated_at": "2026-04-03T11:30:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}Delete Address
Remove an address from the config and reconcile inbound settings if needed. A connected mailbox's push subscription at the provider is deleted first.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentMailbox
Read and organize the live mailbox behind a connected-mailbox address. These are agent tools (channels.mailbox.*). Reading needs `channels:addresses:mailbox:read`, the channel's read access and a receive or both address; organizing needs `channels:addresses:mailbox:modify` and the organize access. Results come straight from the provider and are not stored.
/api/v1/channels/addresses/{address_id}/mailbox/messagesSearch Mailbox Messages
Search the mailbox. Filters combine with AND; `query` adds provider search syntax as is. Returns message summaries; read one with Get Mailbox Message.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
from_address | string | Sender address |
from_domain | string | Sender domain |
to_address | string | Recipient address |
to_domain | string | Recipient domain |
subject | string | Text in the subject |
text | string | Text anywhere in the message |
unread | boolean | Only unread (true) or read (false) mail |
has_attachment | boolean | Only mail with attachments |
received_after | string (date-time) | Received at or after |
received_before | string (date-time) | Received before |
label | string | Gmail label or Microsoft folder or category |
query | string | Provider search syntax (Gmail search or Microsoft KQL), added as is |
limit | integer | Page size, 1 to 100 (default 25) |
page_cursor | string | next_page_cursor from the previous page |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/messages?from_domain=vendor.example&unread=true" \
-H "Authorization: Bearer {token}"Response
200 OK{
"messages": [
{
"id": "18c2f0a9b7e4d001",
"thread_id": "18c2f0a9b7e4d000",
"subject": "Invoice 1042",
"from_address": "billing@vendor.example",
"to": ["support@example.com"],
"received_at": "2026-11-20T09:15:00Z",
"is_unread": true,
"has_attachments": true,
"labels": ["INBOX"],
"snippet": "Please find the invoice attached."
}
],
"next_page_cursor": null
}/api/v1/channels/addresses/{address_id}/mailbox/messageGet Mailbox Message
Read one message with its text, HTML and attachment list.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
message_id* | string | Mailbox message id from Search Mailbox Messages |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/message?message_id=18c2f0a9b7e4d001" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "18c2f0a9b7e4d001",
"thread_id": "18c2f0a9b7e4d000",
"subject": "Invoice 1042",
"from_address": "billing@vendor.example",
"from_name": "Vendor Billing",
"to": ["support@example.com"],
"cc": [],
"received_at": "2026-11-20T09:15:00Z",
"is_unread": true,
"has_attachments": true,
"labels": ["INBOX"],
"snippet": "Please find the invoice attached.",
"text": "Please find the invoice attached.",
"rfc_message_id": "<CA+1042@vendor.example>",
"sent_by_mailbox": false,
"attachments": [
{ "id": "att-1", "filename": "invoice-1042.pdf", "content_type": "application/pdf", "size": 48213, "inline": false }
]
}/api/v1/channels/addresses/{address_id}/mailbox/threadGet Mailbox Thread
Read every message of a mailbox conversation.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
thread_id* | string | thread_id of a mailbox message |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/thread?thread_id=18c2f0a9b7e4d000" \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "18c2f0a9b7e4d000",
"messages": [
{ "id": "18c2f0a9b7e4d001", "subject": "Invoice 1042", "from_address": "billing@vendor.example", "text": "Please find the invoice attached." }
]
}/api/v1/channels/addresses/{address_id}/mailbox/attachmentsList Mailbox Attachments
List a message's attachments without downloading them.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
message_id* | string | Mailbox message id from Search Mailbox Messages |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/attachments?message_id=18c2f0a9b7e4d001" \
-H "Authorization: Bearer {token}"Response
200 OK{
"message_id": "18c2f0a9b7e4d001",
"attachments": [
{ "id": "att-1", "filename": "invoice-1042.pdf", "content_type": "application/pdf", "size": 48213, "inline": false }
]
}/api/v1/channels/addresses/{address_id}/mailbox/attachments/saveSave Mailbox Attachments
Download attachments from the provider and upload them into a Buckets bucket as the caller, who needs upload access to it. Omit attachment_ids to save every non-inline attachment.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Request Body
| Name | Type | Description |
|---|---|---|
message_id* | string | Mailbox message id from Search Mailbox Messages |
bucket_id* | string | Bucket to save into |
folder_id | string | null | Folder in the bucket |
attachment_ids | string[] | null | Attachments to save; omit for all non-inline ones |
curl -X POST https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/attachments/save \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"message_id": "18c2f0a9b7e4d001", "bucket_id": "{bucket_id}"}'Response
200 OK{
"message_id": "18c2f0a9b7e4d001",
"bucket_id": "d4e5f6a7-0000-4000-8000-000000000003",
"files": [
{ "attachment_id": "att-1", "file_id": "e5f6a7b8-0000-4000-8000-000000000004", "filename": "invoice-1042.pdf" }
]
}/api/v1/channels/addresses/{address_id}/mailbox/message/modifyModify Mailbox Message
Mark a message read or unread, archive it, or add and remove labels (Gmail) or categories (Microsoft).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
address_id* | string (UUID) | Connected-mailbox address ID |
Request Body
| Name | Type | Description |
|---|---|---|
message_id* | string | Mailbox message id from Search Mailbox Messages |
mark_read | boolean | null | true marks it read, false marks it unread |
archive | boolean | true moves it out of the inbox |
add_labels | string[] | Labels or categories to add |
remove_labels | string[] | Labels or categories to remove |
curl -X POST https://platform.ergondata.ai/api/v1/channels/addresses/{address_id}/mailbox/message/modify \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"message_id": "18c2f0a9b7e4d001", "mark_read": true, "archive": true}'Response
200 OK{
"id": "18c2f0a9b7e4d001",
"thread_id": "18c2f0a9b7e4d000",
"subject": "Invoice 1042",
"from_address": "billing@vendor.example",
"is_unread": false,
"labels": []
}Send
Queue an outbound message from a verified, active address. Enforces the channels:addresses:send ACL on the address and any matching service access grants.
/api/v1/channels/sendSend Message
Queue a message for asynchronous delivery. For cross-service sends, supply service_name and resource_id so a matching address grant is checked. Pass an optional Idempotency-Key header to make retries safe; a replay returns the original result with idempotent_replay set to true. A connected-mailbox address sends through the mailbox's provider, so the mail appears in its Sent folder; this needs the channel's `send` access.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
channel | string | Channel to use; currently only emailDefault: email |
address_id* | string (UUID) | Sending address ID |
config* | object | Channel-specific payload. For email: to, subject, html, plus optional cc, bcc, reply_to, in_reply_to, and attachments; a connected mailbox also takes reply_to_message_id and reply_all |
service_name | string | null | Calling service slug for grant checks (e.g. workflows) |
resource_id | string | null | External resource ID for grant checks |
Response Fields
| Name | Type | Description |
|---|---|---|
status* | string | Typically queued |
channel* | string | Channel used |
log_id | string | null | Activity log row ID for tracking the send |
provider_id | string | null | Provider slug handling delivery |
provider_message_id | string | null | Outbound SMTP Message-ID set on the email, used for reply correlation |
thread_id | string | null | Channel thread ID for the outbound message |
idempotent_replay | boolean | True when the request matched a prior Idempotency-Key and was not re-dispatchedDefault: false |
curl -X POST https://platform.ergondata.ai/api/v1/channels/send \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: {idempotency_key}" \
-d '{
"channel": "email",
"address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"config": {
"to": ["customer@example.com"],
"subject": "Your order has shipped",
"html": "<p>Thanks for your purchase!</p>",
"reply_to": "support@mail.example.com",
"cc": [],
"bcc": []
},
"service_name": "workflows",
"resource_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}'Response
202 Accepted{
"status": "queued",
"channel": "email",
"log_id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"provider_id": "resend",
"provider_message_id": "<msg_01hqabc@mail.example.com>",
"thread_id": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"idempotent_replay": false
}/api/v1/channels/send/whatsappSend WhatsApp Message
Queue one outbound WhatsApp message from a send-capable address. The typed config carries the recipient and payload: free-form text, bucket-backed media, interactive reply buttons or list menus (all only inside the open 24-hour session window), or an approved template (allowed anytime). Check Get WhatsApp Send Options first to learn the session state and allowed templates.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
channel* | "whatsapp" | Channel discriminator |
address_id* | string (UUID) | Send-capable WhatsApp address the message goes out from |
config* | WhatsAppTextConfig | WhatsAppTemplatePayload | WhatsAppMediaPayload | WhatsAppInteractivePayload | Discriminated by `type` (text | template | media | interactive); every variant carries `to` in E.164 format |
service_name | string | Originating service for attribution |
resource_id | string (UUID) | Originating resource for attribution |
curl -X POST https://platform.ergondata.ai/api/v1/channels/send/whatsapp \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"config": {"type": "text", "to": "+5511999999999", "text": "Your order shipped!"}
}'Response
202 Accepted{
"status": "queued",
"channel": "whatsapp",
"log_id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"provider_id": "whatsapp",
"thread_id": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"idempotent_replay": false
}WhatsApp Templates
Meta-approved message templates synchronized per WhatsApp config. Templates unlock outbound messages outside the 24-hour session window; each template must be explicitly enabled per address before agents can use it.
/api/v1/channels/configs/{config_id}/whatsapp/templatesList WhatsApp Templates
List the templates synchronized from Meta for this config, including approval status, activation state, and the addresses each template is enabled for.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Page size (default 100, max 200) |
offset | integer | Pagination offset (default 0) |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | WhatsAppTemplateResponse[] | Templates with name, language, category, Meta status, rejected_reason (Meta's reason while REJECTED, else null), components, activation state, and allowed_address_ids |
total* | integer | Total templates for the config |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/templates \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "77e3a9b2-1234-4cde-9f00-aabbccddeeff",
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"status": "APPROVED",
"components": [],
"is_active": true,
"allowed_address_ids": ["a1d2e3f4-5566-7788-99aa-bbccddeeff00"],
"last_synced_at": "2026-04-03T14:22:00Z"
}
],
"total": 1
}/api/v1/channels/configs/{config_id}/whatsapp/templates/syncSync WhatsApp Templates
Fetch the current template catalog from Meta and reconcile the local copy: new templates are added, changed ones updated, and removed ones deactivated. Returns the refreshed list.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | WhatsAppTemplateResponse[] | The synchronized template list |
total* | integer | Total templates after the sync |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/templates/sync \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "77e3a9b2-1234-4cde-9f00-aabbccddeeff",
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"status": "APPROVED",
"components": [],
"is_active": true,
"allowed_address_ids": [],
"last_synced_at": "2026-04-05T09:00:00Z"
}
],
"total": 1
}/api/v1/channels/configs/{config_id}/whatsapp/templatesCreate WhatsApp Template
Submit a new UTILITY or MARKETING template to Meta for review on the config's WhatsApp Business Account. The template is stored locally with Meta's initial status (usually PENDING) and is updated by Meta's template status webhook or the next sync. Headers support TEXT only; AUTHENTICATION templates and media headers are not supported yet. Provider rejections map to 422 and Meta rate limits to 429. An active local template with the same name and language returns 409; an inactive one is reused (201, same ID, address allowlists cleared). If Meta already holds that name and language with the same content (a retry), its copy is stored and returned with 201; different content returns 409.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Template name: lowercase letters, digits, and underscores (max 512) |
language* | string | Meta language code such as pt_BR or en_US |
category* | string | UTILITY or MARKETING |
parameter_format | string | POSITIONAL ({{1}}, {{2}}) or NAMED ({{first_name}}) variablesDefault: POSITIONAL |
components* | TemplateComponent[] | Exactly one BODY, plus optional HEADER (TEXT), FOOTER, and BUTTONS. Variables need matching examples. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Local template ID |
status* | string | Meta review status returned at creation, usually PENDING |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/templates \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Olá {{1}}, seu pedido {{2}} foi enviado.",
"example": {"body_text": [["Maria", "1234"]]}
}
]
}'Response
201 Created{
"id": "77e3a9b2-1234-4cde-9f00-aabbccddeeff",
"name": "order_update",
"language": "pt_BR",
"category": "UTILITY",
"status": "PENDING",
"components": [
{
"type": "BODY",
"text": "Olá {{1}}, seu pedido {{2}} foi enviado.",
"example": {"body_text": [["Maria", "1234"]]}
}
],
"is_active": true,
"allowed_address_ids": [],
"last_synced_at": "2026-11-09T14:22:00Z"
}/api/v1/channels/configs/{config_id}/whatsapp/templates/{template_id}Delete WhatsApp Template
Delete one template language from Meta and deactivate the local copy. The template is removed from every address allowlist. Deleting a template that is already inactive is a no-op.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
template_id* | string (UUID) | Local template ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/whatsapp/templates/{template_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentHTTP/1.1 204 No Content/api/v1/channels/configs/{config_id}/addresses/{address_id}/templates/{template_id}Allow Template For Address
Enable one approved template for one address under the config. Agents and API callers can only send templates that are enabled for the sending address.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
address_id* | string (UUID) | WhatsApp address under the config |
template_id* | string (UUID) | Synchronized template ID |
curl -X PUT https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/templates/{template_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentHTTP/1.1 204 No Content/api/v1/channels/configs/{config_id}/addresses/{address_id}/templates/{template_id}Disallow Template For Address
Disable one template for one address under the config. Subsequent sends of that template from the address are rejected.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | WhatsApp business-account config ID |
address_id* | string (UUID) | WhatsApp address under the config |
template_id* | string (UUID) | Synchronized template ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/templates/{template_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentHTTP/1.1 204 No ContentActivity
Inspect the channel type registry, paginated message activity (company-wide or per channel), single events, inbound attachment bytes, and ordered thread transcripts.
/api/v1/channels/channel-typesList Channel Types
Registry of channel implementations (slug, display name, icon, active flag).
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
include_inactive | boolean | Include types marked inactiveDefault: false |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | ChannelTypeItem[] | Channel types |
curl "https://platform.ergondata.ai/api/v1/channels/channel-types?include_inactive=false" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"slug": "email",
"name": "Email",
"icon": "mail",
"is_active": true
}
]/api/v1/channels/companies/{company_id}/activityList Activity
Paginated, company-wide activity log filtered to channels where the caller has channels:activity:view. channels:addresses:receive controls routing eligibility, not activity visibility.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
channel | string | Filter by channel slug |
direction | string | Filter by message direction |
status | string | Comma-separated status slugs |
correlation_id | string | Match a correlation ID |
event_type | string | Filter by event type slug |
search | string | Case-insensitive match on from_address or subject |
date_from | string (ISO 8601) | Inclusive lower bound on created_at |
date_to | string (ISO 8601) | Inclusive upper bound on created_at |
page | integer | Page number (1-based)Default: 1 |
limit | integer | Page size (1–100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | ActivityLogListItem[] | id, event_type, channel, direction, from_address, to_addresses, subject, status, actor_type, error, created_at, optional correlation_id and summary |
total* | integer | Total matching rows |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/activity?page=1&limit=50&channel=email" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"event_type": "channels.email.sent",
"channel": "email",
"direction": "outbound",
"from_address": "Support <support@mail.example.com>",
"to_addresses": ["customer@example.com"],
"subject": "Your order has shipped",
"status": "queued",
"actor_type": "member",
"correlation_id": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"summary": null,
"error": null,
"created_at": "2026-04-06T15:22:11Z"
}
],
"total": 128,
"page": 1,
"limit": 50
}/api/v1/channels/companies/{company_id}/activity/{event_id}Get Activity Event
Full detail for one company activity row, including payload and provider identifiers. Requires channels:activity:view on the row's channel.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
event_id* | string (UUID) | Activity log row ID |
curl https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/activity/{event_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"event_type": "channels.email.sent",
"channel": "email",
"direction": "outbound",
"from_address": "Support <support@mail.example.com>",
"to_addresses": ["customer@example.com"],
"subject": "Your order has shipped",
"status": "delivered",
"actor_type": "member",
"actor_id": "9a000000-0000-4000-8000-000000000001",
"correlation_id": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"summary": null,
"error": null,
"payload": {
"html": "<p>Tracking: <b>1Z999...</b></p>",
"text": "Tracking: 1Z999..."
},
"provider_id": "resend",
"provider_message_id": "<msg_01hqabc@mail.example.com>",
"created_at": "2026-04-06T15:22:11Z"
}/api/v1/channels/configs/{config_id}/activityList Channel Activity
Paginated immutable activity log scoped to a single channel config. Inbound rows require only channels:activity:view on the channel; subscription delivery state is exposed separately by the deliveries and claim APIs.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
direction | string | Filter by message direction |
status | string | Comma-separated status slugs |
correlation_id | string | Match a correlation ID |
event_type | string | Filter by event type slug |
search | string | Case-insensitive match on from_address or subject |
date_from | string (ISO 8601) | Inclusive lower bound on created_at |
date_to | string (ISO 8601) | Inclusive upper bound on created_at |
page | integer | Page number (1-based)Default: 1 |
limit | integer | Page size (1–100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | ActivityLogListItem[] | Activity rows for this channel |
total* | integer | Total matching rows |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"event_type": "channels.email.received",
"channel": "email",
"direction": "inbound",
"from_address": "customer@example.com",
"to_addresses": ["support@mail.example.com"],
"subject": "Question about order #1042",
"status": "delivered",
"actor_type": null,
"correlation_id": null,
"summary": "When will it ship?",
"error": null,
"created_at": "2026-04-06T14:00:00Z"
}
],
"total": 12,
"page": 1,
"limit": 50
}/api/v1/channels/configs/{config_id}/activity/consumptionsList Channel Deliveries
Paginated subscription-scoped delivery history joined to immutable event summaries. Filter by subscription or delivery status to observe ACK/NACK outcomes. Requires channels:activity:view and never returns lease tokens.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
subscription_id | string (UUID) | Return deliveries for one stable subscription |
status | "pending" | "claimed" | "acked" | "failed" | Filter by delivery state |
direction | string | Filter the joined event by direction |
event_status | string | Filter the joined immutable event status |
search | string | Match event type, sender, or subject |
page | integer | Page number (1-based)Default: 1 |
limit | integer | Page size (1–100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | ActivityConsumptionListItem[] | Event summary plus subscription, status, attempts, consumer, and delivery timestamps |
total* | integer | Total matching rows |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/consumptions?status=acked&page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [{
"event": {
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"event_type": "channels.email.received",
"direction": "inbound",
"subject": "Question about order #1042",
"status": "received",
"created_at": "2026-08-15T15:00:00Z"
},
"subscription_id": "11111111-1111-4111-8111-111111111111",
"status": "acked",
"acked_at": "2026-08-15T15:01:00Z",
"available_at": null,
"lease_expires_at": null,
"consumer_id": "inbox-worker-1",
"attempt_count": 1,
"created_at": "2026-08-15T15:00:01Z",
"updated_at": "2026-08-15T15:01:00Z"
}],
"total": 1,
"page": 1,
"limit": 50
}/api/v1/channels/configs/{config_id}/activity/{event_id}Get Channel Activity Event
Full detail for one activity row scoped to a channel config, including payload and provider identifiers. Requires channels:activity:view on the channel.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
event_id* | string (UUID) | Activity log row ID |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/{event_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"event_type": "channels.email.sent",
"channel": "email",
"direction": "outbound",
"from_address": "Support <support@mail.example.com>",
"to_addresses": ["customer@example.com"],
"subject": "Your order has shipped",
"status": "delivered",
"actor_type": "member",
"actor_id": "9a000000-0000-4000-8000-000000000001",
"correlation_id": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"summary": null,
"error": null,
"payload": { "html": "<p>Tracking: 1Z999...</p>" },
"provider_id": "resend",
"provider_message_id": "<msg_01hqabc@mail.example.com>",
"thread_id": "c3d4e5f6-7788-99aa-bbcc-ddeeff001122",
"in_reply_to": null,
"address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"created_at": "2026-04-06T15:22:11Z"
}/api/v1/channels/configs/{config_id}/activity/claimsClaim Inbound Channel Deliveries
Atomically leases canonical channels.email.received deliveries for one inbox address and a stable subscription. Requires both consume and view. Replicas sharing a subscription compete; independent subscriptions each receive the event.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Request Body
| Name | Type | Description |
|---|---|---|
subscription_id* | string (UUID) | Stable connector subscription identity |
address_id* | string (UUID) | Inbox address on this channel whose deliveries to claim |
consumer_id* | string | Current worker or replica identifier |
limit | integer | Maximum deliveries to claim (1–100)Default: 10 |
visibility_timeout_seconds | integer | Lease duration before redelivery (1–3600)Default: 60 |
cursor | string | null | Opaque keyset cursor for continuing the current scan; omit it on a new polling pass |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | ActivityClaimedItem[] | Immutable event plus subscription delivery lease |
next_cursor* | string | null | Cursor after the last claimed immutable event |
idempotent_replay* | boolean | True when Idempotency-Key matched a prior claim and the original batch was returned |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/claims \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: claim-batch-1" \
-d '{"subscription_id":"11111111-1111-4111-8111-111111111111","address_id":"a1d2e3f4-5566-7788-99aa-bbccddeeff00","consumer_id":"inbox-worker-1"}'Response
200 OK{
"items": [{
"event": {"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011", "event_type": "channels.email.received", "address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00"},
"delivery": {
"event_id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"config_id": "8f2c1a00-1111-4222-8333-444455556666",
"subscription_id": "11111111-1111-4111-8111-111111111111",
"status": "claimed",
"lease_token": "22222222-2222-4222-8222-222222222222",
"lease_expires_at": "2026-08-15T16:00:00Z",
"attempt_count": 1
}
}],
"next_cursor": "opaque",
"idempotent_replay": false
}/api/v1/channels/configs/{config_id}/activity/{event_id}/attachments/{attachment_id}/fileDownload Channel Activity Attachment
Stream one inbound email attachment as raw bytes with a bounded size and RFC 6266 filename. Requires channels:activity:view on the channel. attachment_id is payload.attachments[].resend_attachment_id. Unknown-length bodies are buffered up to the limit so oversized files still return 413. Binary transport — not an agent tool.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
event_id* | string (UUID) | Activity log row ID |
attachment_id* | string | Provider attachment id (resend_attachment_id) |
Response Fields
| Name | Type | Description |
|---|---|---|
(body)* | application/octet-stream | … | Raw attachment content |
curl -L -o invoice.pdf \
https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/{event_id}/attachments/{attachment_id}/file \
-H "Authorization: Bearer {token}"Response
200 OK/api/v1/channels/configs/{config_id}/activity/{event_id}/ackAcknowledge Channel Activity Event
Acknowledges one claimed inbound delivery for a subscription using its active lease token. Repeating the same acknowledgement is idempotent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
event_id* | string (UUID) | Activity event ID |
Request Body
| Name | Type | Description |
|---|---|---|
subscription_id* | string (UUID) | Subscription that owns the delivery |
lease_token* | string (UUID) | Active token returned by the claim |
Response Fields
| Name | Type | Description |
|---|---|---|
event_id* | string (UUID) | Event ID |
config_id* | string (UUID) | Channel config ID |
status* | "acked" | Consumption status |
acked_at* | string (ISO 8601) | First acknowledgement time |
idempotent_replay* | boolean | True when already acknowledged |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/{event_id}/ack \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"subscription_id":"11111111-1111-4111-8111-111111111111","lease_token":"22222222-2222-4222-8222-222222222222"}'Response
200 OK{
"event_id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"config_id": "8f2c1a00-1111-4222-8333-444455556666",
"subscription_id": "11111111-1111-4111-8111-111111111111",
"status": "acked",
"acked_at": "2026-08-14T05:00:00Z",
"available_at": null,
"consumer_id": "inbox-worker-1",
"attempt_count": 0,
"idempotent_replay": false
}/api/v1/channels/configs/{config_id}/activity/{event_id}/nackNegatively Acknowledge Channel Activity Event
Requeues or fails one claimed subscription delivery. The body must include the active subscription and lease token. Repeating the same token after a successful nack is an idempotent replay.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
event_id* | string (UUID) | Activity event ID |
Request Body
| Name | Type | Description |
|---|---|---|
subscription_id* | string (UUID) | Subscription that owns the delivery |
lease_token* | string (UUID) | Active token returned by the claim |
requeue | boolean | Return to pending instead of marking failedDefault: true |
delay_seconds | integer | Delay before a requeued event is available (0–86400)Default: 0 |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/activity/{event_id}/nack \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"subscription_id":"11111111-1111-4111-8111-111111111111","lease_token":"22222222-2222-4222-8222-222222222222","requeue":true,"delay_seconds":30}'Response
200 OK{
"event_id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"config_id": "8f2c1a00-1111-4222-8333-444455556666",
"subscription_id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"acked_at": null,
"available_at": "2026-08-14T05:00:30Z",
"consumer_id": "inbox-worker-1",
"attempt_count": 1,
"idempotent_replay": false
}/api/v1/channels/threads/{thread_id}/messagesList Thread Messages
Chronological transcript of a conversation thread, used for automation and agent context. Full inbound message bodies require channels:addresses:receive on each destination address represented in the thread.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
thread_id* | string (UUID) | Conversation thread ID |
Response Fields
| Name | Type | Description |
|---|---|---|
messages* | ThreadMessageItem[] | id, direction, from_address, to_addresses, subject, status, actor_type, html, text, created_at |
curl https://platform.ergondata.ai/api/v1/channels/threads/{thread_id}/messages \
-H "Authorization: Bearer {token}"Response
200 OK{
"messages": [
{
"id": "b2c3d4e5-6677-8899-aabb-ccddeeff0011",
"direction": "inbound",
"from_address": "customer@example.com",
"to_addresses": ["support@mail.example.com"],
"subject": "Question about order #1042",
"status": "delivered",
"actor_type": null,
"html": "<p>When will it ship?</p>",
"text": null,
"created_at": "2026-04-06T14:00:00Z"
},
{
"id": "c3d4e5f6-7788-9900-bbcc-ddeeff002233",
"direction": "outbound",
"from_address": "Support <support@mail.example.com>",
"to_addresses": ["customer@example.com"],
"subject": "Re: Question about order #1042",
"status": "delivered",
"actor_type": "member",
"html": "<p>It ships tomorrow morning.</p>",
"text": null,
"created_at": "2026-04-06T14:05:22Z"
}
]
}Service grants
Service grants let another service (for example workflows) send from a specific address when its service_name and resource_id match. They are distinct from address ACL grants and from channel-zone access grants.
/api/v1/channels/addresses/grantedList Granted Addresses
Addresses the caller may use for a given service (and optional resource), typically when configuring a template in another product.
Bearer token required. Company context from the member token or x-company-id header.
Query Parameters
| Name | Type | Description |
|---|---|---|
service* | string | Service slug to match stored grants |
resource_id | string | Further narrow to one external resource |
sendable | boolean | When true, restrict to addresses eligible to sendDefault: false |
channel_type | string | Filter by underlying config channel type |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | GrantedAddressResponse[] | id, channel_config_id, address, display_name, direction, status, channel_type, channel_name, timestamps |
curl "https://platform.ergondata.ai/api/v1/channels/addresses/granted?service=workflows&resource_id=f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Authorization: Bearer {token}" \
-H "x-company-id: {company_id}"Response
200 OK[
{
"id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"channel_config_id": "8f2c1a00-1111-4222-8333-444455556666",
"address": "hello@mail.example.com",
"display_name": "Support",
"direction": "send",
"status": "active",
"channel_type": "email",
"channel_name": "Primary email",
"created_at": "2026-04-02T10:00:00Z",
"updated_at": "2026-04-02T10:00:00Z"
}
]/api/v1/channels/configs/{config_id}/addresses/{address_id}/grantsList Grants
Return the service grants attached to an address.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | GrantResponse[] | id, address_id, company_id, service_name, resource_id, resource_label, label, created_by, created_at |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/grants \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "a7c9e1d2-3344-4566-8788-99aabbccddee",
"address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"service_name": "workflows",
"resource_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"resource_label": "Order notifications",
"label": "Production",
"created_by": "9a000000-0000-4000-8000-000000000001",
"created_at": "2026-04-05T12:00:00Z"
}
]/api/v1/channels/configs/{config_id}/addresses/{address_id}/grantsCreate Grant
Record that an external service may send using this address for a given resource scope.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_name* | string | Calling service slug (1–50 characters) |
resource_id | string | null | Scoped resource in the calling service |
resource_label | string | null | Human-readable resource label |
label | string | null | Optional note for operators |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"service_name": "workflows",
"resource_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"resource_label": "Order notifications",
"label": "Production"
}'Response
201 Created{
"id": "a7c9e1d2-3344-4566-8788-99aabbccddee",
"address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"service_name": "workflows",
"resource_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"resource_label": "Order notifications",
"label": "Production",
"created_by": "9a000000-0000-4000-8000-000000000001",
"created_at": "2026-04-05T12:00:00Z"
}/api/v1/channels/grants/{grant_id}Revoke Grant
Revoke a service grant by ID.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
grant_id* | string (UUID) | Grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/grants/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentAddress ACL
Per-address ACL grants control which IAM principals or roles may send from a specific address or view inbound messages received at it. Receive grants authorize visibility; they do not enable, disable, deliver, or route inbound mail.
/api/v1/channels/configs/{config_id}/addresses/{address_id}/aclList Address ACL
List ACL grants for a specific address — the permission grants that control who can use this address.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | GrantResponse[] | id, principal_type, principal_id, principal_label, permission_name, resource, effect, granted_at |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"principal_label": "Jane Doe",
"permission_name": "channels:addresses:send",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666/address/a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"effect": "allow",
"granted_at": "2026-04-05T10:00:00Z"
}
]/api/v1/channels/configs/{config_id}/addresses/{address_id}/aclGrant Address ACL
Grant a principal an address permission. Send maps to channels:addresses:send. Receive maps to channels:addresses:receive and makes the principal eligible as an inbound subscriber; activity visibility remains governed by channels:activity:view.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal kind: member, api_key, or agent |
principal_id* | string | Principal identifier |
capability | string | send or receiveDefault: send |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Grant ID |
principal_type* | string | Principal kind |
principal_id* | string | Principal identifier |
principal_label* | string | Resolved display name |
permission_name* | string | Permission slug granted |
resource* | string | Scoped resource URN |
effect* | string | Grant effect (allow) |
granted_at* | string (ISO 8601) | When the grant was created |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"capability": "send"
}'Response
201 Created{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"principal_label": "Jane Doe",
"permission_name": "channels:addresses:send",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666/address/a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"effect": "allow",
"granted_at": "2026-04-05T10:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl/{grant_id}Revoke Address ACL
Revoke a permission grant on this address.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
grant_id* | string (UUID) | ACL grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/api/v1/channels/configs/{config_id}/addresses/{address_id}/eligible-principalsList Eligible Principals
List principals that can be granted ACL on this address, for building a grant picker.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
address_id* | string (UUID) | Address ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | EligiblePrincipal[] | principal_type, principal_id, label |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/eligible-principals \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"label": "Jane Doe"
}
]/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/eligibleList Address Access Eligibility
List principals eligible on the concrete address. Requires channels:permissions:manage and forwards the optional permission filter to IAM.
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
permission | string | Filter to principals eligible for this permission, such as channels:addresses:receive or channels:addresses:send |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | EligiblePrincipal[] | principal_type, principal_id, label |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/eligible?permission=channels%3Aaddresses%3Areceive" -H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"label": "Jane Doe"
}
]/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/resource-typesList Address Access Resource Types
List grantable address permissions and resource types. Directional send/receive permissions are filtered to the address direction.
Bearer token with channels:permissions:manage on the address.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Parent channel config ID |
address_id* | string (UUID) | Channel address ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | ResourceTypeNode[] | Channels resource-type tree |
permissions* | PermissionOption[] | Permissions valid for this address |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/resource-types \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [],
"permissions": [{
"id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:addresses:receive",
"scope_anchor": "instance",
"display_order": 0
}]
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grantsList Address Access Grants
List paginated IAM grants scoped to one channel address.
Bearer token with channels:permissions:manage on the address.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Parent channel config ID |
address_id* | string (UUID) | Channel address ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (1-based)Default: 1 |
limit | integer | Page size (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantEntry[] | Address-scoped grants |
total* | integer | Total grants |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants?page=1&limit=100" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [],
"total": 0,
"page": 1,
"limit": 100
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grantsCreate Address Access Grant
Grant one catalog permission on the concrete address. Send and receive permissions must match the address direction.
Bearer token with channels:permissions:manage on the address.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Parent channel config ID |
address_id* | string (UUID) | Channel address ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | "member" | "api_key" | "agent" | "role" | "team" | IAM principal kind |
principal_id* | string (UUID) | IAM principal ID |
permission_id* | string (UUID) | Permission UUID from this address's resource-types response |
resource | string | null | Must equal this address resource when provided |
effect | string | Grant effectDefault: allow |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"principal_type":"agent","principal_id":"{principal_id}","permission_id":"{permission_id}"}'Response
201 Created{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"permission_id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:addresses:receive",
"resource": "org/{company_id}/channel/{config_id}/address/{address_id}",
"effect": "allow",
"is_system": false,
"granted_at": "2026-08-06T12:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants/{grant_id}Delete Address Access Grant
Revoke one IAM grant scoped to the channel address.
Bearer token with channels:permissions:manage on the address.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Parent channel config ID |
address_id* | string (UUID) | Channel address ID |
grant_id* | string (UUID) | IAM grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentInbound Config
Configure how a receivable address handles new inbound conversations: an optional Workflows entry-phase handler plus user and team subscribers. Conversations binds exactly one conversation per external thread and creates a workflow item only when a handler is set.
/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-configGet Address Inbound Config
Return the inbound handler and subscribers for an address. Creates an empty config on first read. Requires channels:addresses:manage on the address.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Inbound-config ID |
company_id* | string (UUID) | Owning company |
channel_address_id* | string (UUID) | Receiving address |
workflow_entry_phase_id* | string (UUID) | null | Workflow entry phase that receives new inbound items; null means no handler |
subscribers* | InboundSubscriber[] | Users and teams that join new inbound conversations |
created_at* | string (ISO 8601) | Creation time |
updated_at* | string (ISO 8601) | Last update time |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config -H "Authorization: Bearer {token}"Response
200 OK{
"id": "70000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"workflow_entry_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"subscribers": [{
"id": "80000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"inbound_config_id": "70000000-0000-4000-8000-000000000001",
"principal_type": "user",
"principal_id": "66666666-6666-4666-8666-666666666666",
"role": "observer",
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}],
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscriber-candidatesList Inbound Subscriber Candidates
List same-company users and teams that can be added as inbound subscribers, including principals not yet connected to Channels. Requires channels:addresses:manage on the address.
Bearer token required.
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Page size (1–500)Default: 100 |
offset | integer | Number of candidates to skipDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | InboundSubscriberCandidate[] | Same-company users and teams available as subscribers |
total* | integer | Total matching principals |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscriber-candidates?limit=100&offset=0" -H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"principal_type": "user",
"principal_id": "66666666-6666-4666-8666-666666666666",
"label": "Support engineer"
}
],
"total": 1
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/handlerUpdate Address Inbound Handler
Set or clear the workflow entry phase that receives new inbound items. Requires channels:addresses:manage on the address and workflows:workflows:items:create on the selected phase.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
workflow_entry_phase_id | string (UUID) | null | Entry phase that can create items; null clears the handler |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Inbound-config ID |
company_id* | string (UUID) | Owning company |
channel_address_id* | string (UUID) | Receiving address |
workflow_entry_phase_id* | string (UUID) | null | Workflow entry phase that receives new inbound items; null means no handler |
subscribers* | InboundSubscriber[] | Users and teams that join new inbound conversations |
created_at* | string (ISO 8601) | Creation time |
updated_at* | string (ISO 8601) | Last update time |
curl -X PUT https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/handler -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"workflow_entry_phase_id":"{phase_id}"}'Response
200 OK{
"id": "70000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"channel_address_id": "a1d2e3f4-5566-7788-99aa-bbccddeeff00",
"workflow_entry_phase_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"subscribers": [{
"id": "80000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"inbound_config_id": "70000000-0000-4000-8000-000000000001",
"principal_type": "user",
"principal_id": "66666666-6666-4666-8666-666666666666",
"role": "observer",
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}],
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribersAdd Address Inbound Subscriber
Add a same-company user, team, or service agent subscriber; a personal agent is refused with 422 (it only works for its owner). A person or team joins as observer or participant. An agent joins as participant only, at most one per address, and not beside a workflow handler. Requires channels:addresses:manage on the address. This provisions conversation access only.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | "user" | "team" | Subscriber identity kind |
principal_id* | string (UUID) | Canonical principal ID |
role* | "observer" | "participant" | Conversation membership role |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Subscriber ID |
company_id* | string (UUID) | Owning company |
inbound_config_id* | string (UUID) | Parent inbound-config ID |
principal_type* | "user" | "team" | Subscriber identity kind |
principal_id* | string (UUID) | Canonical principal ID |
role* | "observer" | "participant" | Conversation membership role for new inbound threads |
created_at* | string (ISO 8601) | Creation time |
updated_at* | string (ISO 8601) | Last update time |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"principal_type":"user","principal_id":"{principal_id}","role":"observer"}'Response
201 Created{
"id": "80000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"inbound_config_id": "70000000-0000-4000-8000-000000000001",
"principal_type": "user",
"principal_id": "66666666-6666-4666-8666-666666666666",
"role": "observer",
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers/{subscriber_id}Update Address Inbound Subscriber
Change a subscriber role. Requires channels:addresses:manage on the address.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
role* | "observer" | "participant" | Conversation membership role |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Subscriber ID |
company_id* | string (UUID) | Owning company |
inbound_config_id* | string (UUID) | Parent inbound-config ID |
principal_type* | "user" | "team" | Subscriber identity kind |
principal_id* | string (UUID) | Canonical principal ID |
role* | "observer" | "participant" | Conversation membership role for new inbound threads |
created_at* | string (ISO 8601) | Creation time |
updated_at* | string (ISO 8601) | Last update time |
curl -X PATCH https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers/{subscriber_id} -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"role":"participant"}'Response
200 OK{
"id": "80000000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"inbound_config_id": "70000000-0000-4000-8000-000000000001",
"principal_type": "user",
"principal_id": "66666666-6666-4666-8666-666666666666",
"role": "observer",
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:00:00Z"
}/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers/{subscriber_id}Remove Address Inbound Subscriber
Remove a subscriber. Requires channels:addresses:manage on the address.
Bearer token required.
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers/{subscriber_id} -H "Authorization: Bearer {token}"Response
204 No ContentChannel zone access
Govern the zero-trust channel zone rooted at a config: enumerate resource types and permissions, manage zone-level access grants, list principals eligible for access, and approve, reject, or sever inbound connection requests from other principals.
/api/v1/channels/configs/{config_id}/access/grantsList Access Grants
Paginated list of access grants on this channel zone.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (1-based)Default: 1 |
limit | integer | Page size (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantResponse[] | id, permission_id, name, resource, effect, is_system, granted_at |
total | integer | Total matching rows |
page | integer | Current page |
limit | integer | Page size |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/grants?page=1&limit=100" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"permission_id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:channels:manage",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"effect": "allow",
"is_system": false,
"granted_at": "2026-04-05T10:00:00Z"
}
],
"total": 3,
"page": 1,
"limit": 100
}/api/v1/channels/configs/{config_id}/access/grantsCreate Access Grant
Grant a permission on this channel zone (or a nested resource) to a principal.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal kind: member, api_key, agent, or role |
principal_id* | string | Principal identifier |
permission_id* | string | Permission to grant (from List Channel Permissions) |
resource | string | null | Resource URN to scope the grant to; defaults to the channel zone |
effect | string | Grant effectDefault: allow |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string | Grant ID |
permission_id* | string | Permission granted |
name* | string | Permission slug |
resource* | string | Scoped resource URN |
effect* | string | Grant effect |
is_system* | boolean | Whether the grant is system-managed |
granted_at* | string (ISO 8601) | When the grant was created |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"permission_id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"effect": "allow"
}'Response
201 Created{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"permission_id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:channels:manage",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"effect": "allow",
"is_system": false,
"granted_at": "2026-04-05T10:00:00Z"
}/api/v1/channels/configs/{config_id}/access/grants/{grant_id}Delete Access Grant
Revoke an access grant on this channel zone by ID.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
grant_id* | string (UUID) | Access grant ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/grants/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/api/v1/channels/configs/{config_id}/access/permissionsList Channel Permissions
Permissions that can be granted on this channel zone and its resources.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | PermissionOption[] | id, name, friendly_name, description, scope_anchor, display_order, resource_type_id, parent_resource_type_slug |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/permissions \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:addresses:send",
"friendly_name": "Send",
"friendly_name_singular": "Send",
"description": "Send messages from this address",
"scope_anchor": "instance",
"display_order": 10,
"resource_type_id": "2b1c0d9e-8f7a-4b6c-9d5e-4f3a2b1c0d9e",
"parent_resource_type_slug": "channel"
}
]/api/v1/channels/configs/{config_id}/access/resource-typesList Resource Types
Resource-type tree for the channel zone plus the permissions available at each level, for building an access editor.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | ResourceTypeNode[] | Nested resource types (id, name, slug, parent_id, children) |
permissions* | PermissionOption[] | Permissions available across the tree |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/resource-types \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{
"id": "2b1c0d9e-8f7a-4b6c-9d5e-4f3a2b1c0d9e",
"name": "Channel",
"slug": "channel",
"parent_id": null,
"children": [
{
"id": "3c2d1e0f-9a8b-4c7d-8e6f-5a4b3c2d1e0f",
"name": "Address",
"slug": "address",
"parent_id": "2b1c0d9e-8f7a-4b6c-9d5e-4f3a2b1c0d9e",
"children": []
}
]
}
],
"permissions": [
{
"id": "7e5d6c4b-3a21-4f09-8e7d-6c5b4a392817",
"name": "channels:addresses:send",
"friendly_name": "Send",
"scope_anchor": "instance"
}
]
}/api/v1/channels/configs/{config_id}/access/eligibleList Eligible Principals
Principals eligible to receive access on this channel zone, for building a grant picker.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | EligiblePrincipal[] | principal_type, principal_id, label |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/eligible \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "9a000000-0000-4000-8000-000000000001",
"label": "Jane Doe"
}
]/api/v1/channels/configs/{config_id}/access/connection-requestsList Connection Requests
List requests from other principals asking to connect to this channel zone.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | Filter by request statusDefault: pending |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | ConnectionRequestEntry[] | id, principal_id, target_service, target_resource, status, created_at, plus optional connection_id, requested_by, requested_permissions, message, decided_at, decided_by |
curl "https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/connection-requests?status=pending" \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "11112222-3333-4444-5555-666677778888",
"principal_id": "9a000000-0000-4000-8000-000000000002",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"status": "pending",
"requested_by": "9a000000-0000-4000-8000-000000000002",
"requested_permissions": ["channels:addresses:send"],
"message": "Need to send order notifications",
"connection_id": null,
"decided_at": null,
"decided_by": null,
"created_at": "2026-04-05T09:00:00Z"
}
]/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/approveApprove Connection Request
Approve a pending connection request, optionally granting a specific set of permissions.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
request_id* | string (UUID) | Connection request ID |
Request Body
| Name | Type | Description |
|---|---|---|
grant | boolean | Whether to grant access on approvalDefault: true |
permissions | string[] | null | Permission slugs to grant; defaults to the requested permissions |
label | string | null | Optional label for the resulting connection |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/approve \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"grant": true,
"permissions": ["channels:addresses:send"],
"label": "Order notifications"
}'Response
200 OK{
"id": "11112222-3333-4444-5555-666677778888",
"principal_id": "9a000000-0000-4000-8000-000000000002",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"status": "approved",
"requested_by": "9a000000-0000-4000-8000-000000000002",
"requested_permissions": ["channels:addresses:send"],
"message": "Need to send order notifications",
"connection_id": "aaaa1111-2222-4333-8444-555566667777",
"decided_at": "2026-04-05T09:30:00Z",
"decided_by": "9a000000-0000-4000-8000-000000000001",
"created_at": "2026-04-05T09:00:00Z"
}/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/rejectReject Connection Request
Reject a pending connection request with an optional reason.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
request_id* | string (UUID) | Connection request ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional rejection reason |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/reject \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "Not needed"}'Response
200 OK{
"id": "11112222-3333-4444-5555-666677778888",
"principal_id": "9a000000-0000-4000-8000-000000000002",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"status": "rejected",
"requested_by": "9a000000-0000-4000-8000-000000000002",
"requested_permissions": ["channels:addresses:send"],
"message": "Need to send order notifications",
"connection_id": null,
"decided_at": "2026-04-05T09:30:00Z",
"decided_by": "9a000000-0000-4000-8000-000000000001",
"created_at": "2026-04-05T09:00:00Z"
}/api/v1/channels/configs/{config_id}/access/connectionsList Inbound Connections
List active connections where another principal connects to this channel zone.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | InboundConnectionEntry[] | id, principal_id, target_service, target_resource, created_at, plus optional principal_type, principal_label, label, created_by, created_by_label, requested_by, requested_by_label, system_managed_by |
curl https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/connections \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "aaaa1111-2222-4333-8444-555566667777",
"principal_id": "9a000000-0000-4000-8000-000000000002",
"principal_type": "automation",
"principal_label": "Order notifier",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/channel/8f2c1a00-1111-4222-8333-444455556666",
"label": "Order notifications",
"created_by": "9a000000-0000-4000-8000-000000000001",
"created_by_label": "Jane Doe",
"requested_by": "9a000000-0000-4000-8000-000000000002",
"requested_by_label": "Order notifier",
"system_managed_by": null,
"created_at": "2026-04-05T09:30:00Z"
}
]/api/v1/channels/configs/{config_id}/access/connections/{connection_id}Revoke Inbound Connection
Sever an inbound connection to this channel, cutting the principal's runtime access.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Channel config ID |
connection_id* | string (UUID) | Connection ID |
curl -X DELETE https://platform.ergondata.ai/api/v1/channels/configs/{config_id}/access/connections/{connection_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentWebhooks
Inbound provider callbacks. These endpoints are called by the email provider and by Meta when they deliver events; they are not invoked directly by API consumers.
/api/v1/channels/webhooks/emailReceive Email
Provider webhook for inbound email. The email provider posts delivery and inbound-message events here; the body is provider-specific and verified by signature. Inbound messages route to the matching receive/both address and may emit channel events. IAM receive grants are not evaluated for provider delivery or routing; they govern subsequent message visibility.
Called by the email provider. Authenticated by provider webhook signature, not a bearer token.
Request Body
| Name | Type | Description |
|---|---|---|
<provider payload>* | object | Provider-specific event envelope (e.g. message, headers, recipients) |
curl -X POST https://platform.ergondata.ai/api/v1/channels/webhooks/email \
-H "Content-Type: application/json" \
-H "svix-signature: {provider_signature}" \
-d '{
"type": "email.received",
"data": {
"from": "customer@example.com",
"to": ["support@mail.example.com"],
"subject": "Question about order #1042"
}
}'Response
200 OK{ "ok": true }/api/v1/channels/webhooks/connected-mailbox/{provider}Verify Connected Mailbox Webhook
Push-subscription validation for a mailbox provider; the provider module answers its handshake. Returns 404 for a provider that is not available or does not push. Gmail (Cloud Pub/Sub) has no handshake and answers 405. Not invoked by API consumers.
Validated by the provider module; no bearer token.
Path Parameters
| Name | Type | Description |
|---|---|---|
provider* | "gmail" | "microsoft" | Mailbox provider |
curl "https://platform.ergondata.ai/api/v1/channels/webhooks/connected-mailbox/microsoft?validationToken=abc123"Response
200 OKabc123/api/v1/channels/webhooks/connected-mailbox/{provider}Receive Connected Mailbox Webhook
Push notification from a mailbox provider. The provider module validates it; a valid notification marks the named mailbox due, and the receive loop then reads the new mail from the provider. A subscription lifecycle notification also acts on the subscription: when the provider removed it, the next sync creates a new one; when it asks for reauthorization, the next sync renews it. A notification counts only for a mailbox with an active push subscription whose client state it carries, so a polled mailbox is never woken. Bodies over the size limit answer 413, invalid ones 400, and an unavailable provider 404. Gmail is a Cloud Pub/Sub push subscription with authentication, pointed at `setup_details.mailbox.webhook_url`: it answers 204, 401 without a valid Google-signed token, and 503 when no audience is configured, and a push wakes only mailboxes watched for the token's service account. Not invoked by API consumers.
Validated by the provider module: Microsoft 365 by the subscription's client state; Gmail by a Google-signed OIDC bearer token (`Authorization: Bearer`) for the channel's push service account.
Path Parameters
| Name | Type | Description |
|---|---|---|
provider* | "gmail" | "microsoft" | Mailbox provider |
Request Body
| Name | Type | Description |
|---|---|---|
<provider payload>* | object | Provider-specific notification |
curl -X POST https://platform.ergondata.ai/api/v1/channels/webhooks/connected-mailbox/microsoft \
-H "Content-Type: application/json" \
-d '{"value": [{"subscriptionId": "{subscription_id}", "clientState": "{client_state}"}]}'Response
202 Accepted/api/v1/channels/webhooks/whatsappVerify Platform WhatsApp App Webhook
Meta's webhook subscription handshake for the platform's own Meta app (Tech Provider / Embedded Signup). When hub.verify_token matches the platform verify token, the challenge is echoed back as plain text. Returns 404 while the platform Meta app is not configured. Not invoked by API consumers.
Authenticated by the platform verify token; no bearer token.
Query Parameters
| Name | Type | Description |
|---|---|---|
hub.mode* | string | Must be "subscribe" |
hub.challenge* | string | Random challenge Meta expects echoed back |
hub.verify_token* | string | Verify token compared against the platform verify token |
curl "https://platform.ergondata.ai/api/v1/channels/webhooks/whatsapp?hub.mode=subscribe&hub.challenge=12345&hub.verify_token={verify_token}"Response
200 OK12345/api/v1/channels/webhooks/whatsappReceive Platform WhatsApp App Webhook
Single Meta Cloud API callback for every WhatsApp Business Account connected through the platform's Meta app. The body is verified with the X-Hub-Signature-256 HMAC computed from the platform app secret, then each entry is routed by WABA ID to the matching config; phone numbers that do not belong to that config are rejected per change. Unknown WABAs and configs of another app are logged and acknowledged with 200, while a known config whose setup is not ready yet answers 503 so Meta redelivers; partner lifecycle events are routed and counted without changing the config status. An unexpected error for one WABA keeps the other tenants' work and answers 503 so Meta redelivers (receipts make the replay idempotent). Returns 404 while the platform Meta app is not configured. Not invoked by API consumers.
Authenticated by the X-Hub-Signature-256 HMAC signature of the platform Meta app; no bearer token.
Request Body
| Name | Type | Description |
|---|---|---|
<Meta payload>* | object | Meta Cloud API event envelope; entry[].id is the WABA ID (partner events carry it in value.waba_info.waba_id) |
curl -X POST https://platform.ergondata.ai/api/v1/channels/webhooks/whatsapp \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: sha256={signature}" \
-d '{"object":"whatsapp_business_account","entry":[]}'Response
200 OK{ "status": "ok", "processed": 0, "routed": 0, "ignored": 0, "rejected": 0, "partner_events": 0 }/api/v1/channels/webhooks/whatsapp/{webhook_token}Verify WhatsApp Webhook
Meta's webhook subscription handshake. Meta calls this endpoint with hub.mode, hub.challenge, and hub.verify_token; when the verify token matches the Vault-stored secret for the config, the challenge is echoed back as plain text. Not invoked by API consumers.
Authenticated by the per-config webhook token in the path plus the Vault-stored verify token; no bearer token.
Path Parameters
| Name | Type | Description |
|---|---|---|
webhook_token* | string | Per-config opaque webhook token issued during WhatsApp setup |
Query Parameters
| Name | Type | Description |
|---|---|---|
hub.mode* | string | Must be "subscribe" |
hub.challenge* | string | Random challenge Meta expects echoed back |
hub.verify_token* | string | Verify token compared against the Vault-stored secret |
curl "https://platform.ergondata.ai/api/v1/channels/webhooks/whatsapp/{webhook_token}?hub.mode=subscribe&hub.challenge=12345&hub.verify_token={verify_token}"Response
200 OK12345/api/v1/channels/webhooks/whatsapp/{webhook_token}Receive WhatsApp Webhook
Meta Cloud API callback for inbound messages, delivery statuses, account updates, and template status changes. The body is verified with the X-Hub-Signature-256 HMAC computed from the Vault-stored app secret. Inbound messages route to the matching WhatsApp address and drive episodic conversations. Not invoked by API consumers.
Authenticated by the per-config webhook token in the path plus the X-Hub-Signature-256 HMAC signature; no bearer token.
Path Parameters
| Name | Type | Description |
|---|---|---|
webhook_token* | string | Per-config opaque webhook token issued during WhatsApp setup |
Request Body
| Name | Type | Description |
|---|---|---|
<Meta payload>* | object | Meta Cloud API event envelope (entry, changes, messages, statuses) |
curl -X POST https://platform.ergondata.ai/api/v1/channels/webhooks/whatsapp/{webhook_token} \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: sha256={signature}" \
-d '{"object":"whatsapp_business_account","entry":[]}'Response
200 OK{ "ok": true }Batch Access Grants
Public batch grant routes accept BatchCreateGrantsRequest and return ordered BatchCreateGrantsResponse partial-success envelopes. Operations expand as resources × permission_ids with a maximum of 200 expanded grants. HTTP 200 may include failed items; `already_exists` is an idempotent success, so whole-request or failed-item retries are safe. Side-effect errors do not roll back successful grants and require separate reconciliation.
/api/v1/channels/configs/access/grants/batchBatch Create Channel Grants
Create grants across channel-config roots with independent per-item validation. Agent ToolDef slug: `channels.channel_access.create_grants_batch`.
Bearer token and company context required. IAM permission `channels:permissions:manage` on every concrete channel root.
Request Body
| Name | Type | Description |
|---|---|---|
operations* | BatchGrantOperation[] | One or more grouped operations; maximum 200 expanded grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | BatchGrantResult[] | Ordered results with index, client_ref, status, principal, permission_id, canonical resource, effect, grant, error_status/error_detail, and side_effect_error_status/side_effect_error_detail |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/api/v1/channels/configs/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"client_ref":"channel-access","principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/channel/{config_id}"],"permission_ids":["{permission_id}"],"effect":"allow"}]}'Response
200 OK{
"results": [{
"index": 0, "client_ref": "channel-access", "status": "created",
"principal_type": "member", "principal_id": "{principal_id}",
"permission_id": "{permission_id}", "resource": "org/{company_id}/channel/{config_id}",
"effect": "allow", "grant": {}, "error_status": null, "error_detail": null,
"side_effect_error_status": null, "side_effect_error_detail": null
}],
"summary": { "created": 1, "already_exists": 0, "failed": 0 }
}/api/v1/channels/addresses/access/grants/batchBatch Create Address Grants
Create grants across address roots. Address resources must end at the address root, and directional permissions must match the address's send/receive/both direction. Agent ToolDef slug: `channels.address_access.create_grants_batch`.
Bearer token and company context required. IAM permission `channels:permissions:manage` on every concrete address root.
Request Body
| Name | Type | Description |
|---|---|---|
operations* | BatchGrantOperation[] | BatchCreateGrantsRequest operations (client_ref, principal_type/id, resources, permission_ids, effect); maximum 200 expanded grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | BatchGrantResult[] | Ordered partial-success results with primary and side-effect error fields |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/api/v1/channels/addresses/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"agent","principal_id":"{principal_id}","resources":["org/{company_id}/channel/{config_id}/address/{address_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{
"index": 0, "client_ref": null, "status": "already_exists",
"principal_type": "agent", "principal_id": "{principal_id}",
"permission_id": "{permission_id}", "resource": "org/{company_id}/channel/{config_id}/address/{address_id}",
"effect": "allow", "grant": {}, "error_status": null, "error_detail": null,
"side_effect_error_status": null, "side_effect_error_detail": null
}],
"summary": { "created": 0, "already_exists": 1, "failed": 0 }
}