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`.

Base URL/api/v1/channels

Automation 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}.

POST/api/v1/channels/configs

Create 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

NameTypeDescription
name*
stringDisplay 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
stringCustomer-owned domain for custom-domain (3–253 characters). Omit for platform-domain.
channel_type
stringChannel implementation slugDefault: email

Response Fields

NameTypeDescription
id*
stringConfig ID
company_id*
stringOwning company ID
channel_type*
stringChannel type slug
integration_type*
"platform-domain" | "custom-domain" | "connected-mailbox" | "business-account"Provider-neutral setup model for email and WhatsApp Business accounts.
name*
stringDisplay name
domain*
string | nullConfigured domain
status*
stringLifecycle status (e.g. pending_dns, verifying, verified)
setup_details*
object | nullSafe, 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*
booleanWhether inbound handling is enabled for this config
created_at*
stringCreation time (ISO 8601)
updated_at*
stringLast update time (ISO 8601)
capabilities
objectWhat 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
  }
}
GET/api/v1/channels/configs

List Configs

Return all channel configs visible to the caller for their company.

Bearer token required. x-company-id header required.

Response Fields

NameTypeDescription
[]*
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 }
  }
]
GET/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

NameTypeDescription
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 }
}
PATCH/api/v1/channels/configs/{config_id}

Update Config

Update the display name for a config.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Request Body

NameTypeDescription
name
string | nullNew 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"
}
POST/api/v1/channels/configs/{config_id}/verify

Verify Config

Verify DNS for a Custom Domain and move it toward verified. Platform Domain requires no DNS verification.

Bearer token required.

Path Parameters

NameTypeDescription
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"
}
GET/api/v1/channels/configs/{config_id}/whatsapp/phone-numbers

Discover 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

NameTypeDescription
config_id*
string (UUID)Ready WhatsApp business-account config ID

Response Fields

NameTypeDescription
items*
WhatsAppPhoneNumberCandidate[]Meta-derived phone IDs, normalized numbers, verification/quality state, and local connected state
total*
integerNumber 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
}
POST/api/v1/channels/configs/{config_id}/whatsapp/phone-numbers

Add 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

NameTypeDescription
config_id*
string (UUID)Ready WhatsApp business-account config ID

Request Body

NameTypeDescription
phone_number_id*
stringMeta 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"
}
GET/api/v1/channels/configs/whatsapp/embedded-signup

Get 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"
}
POST/api/v1/channels/configs/whatsapp/embedded-signup

Connect 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

NameTypeDescription
name*
stringChannel name
code*
stringExchangeable code from `FB.login` (response_type `code`)
waba_id
stringWABA ID from the session event; when omitted the single WABA granted to the token is used
phone_number_id
stringPhone number ID from the session event; when omitted a WABA with exactly one number connects that number
business_id
stringCustomer business portfolio ID from the session event
event
stringSession event type; `FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING` keeps the number on the WhatsApp Business app (coexistence) and skips Cloud API registration
config_id
uuidReconnect 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"
}
POST/api/v1/channels/configs/{config_id}/whatsapp/credentials/connect

Connect 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

NameTypeDescription
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"
}
DELETE/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

NameTypeDescription
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 Content

Connected 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.

GET/api/v1/channels/configs/connected-mailbox/providers

List 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

NameTypeDescription
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 }
          ]
        }
      ]
    }
  ]
}
POST/api/v1/channels/configs/connected-mailbox

Create 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

NameTypeDescription
name*
stringChannel name
provider*
"gmail" | "microsoft"Mailbox provider
auth_method*
"user_oauth" | "service_account" | "app_registration"How the channel reaches the mailboxes
credentials
objectConnect-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

NameTypeDescription
config*
objectThe 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 | nullThe 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 }
  ]
}
POST/api/v1/channels/configs/{config_id}/connected-mailbox/finalize

Finalize 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

NameTypeDescription
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" }
  ]
}
POST/api/v1/channels/configs/{config_id}/connected-mailbox/mailboxes

Add 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

NameTypeDescription
config_id*
string (UUID)Connected-mailbox config ID

Request Body

NameTypeDescription
address*
stringMailbox email address
direction
"send" | "receive" | "both"receive reads it, send sends from it, both does bothDefault: both
display_name
string | nullDisplay name
credentials
objectOnly 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
}
POST/api/v1/channels/configs/{config_id}/connected-mailbox/credentials

Replace 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

NameTypeDescription
config_id*
string (UUID)Connected-mailbox config ID

Request Body

NameTypeDescription
credentials*
objectThe 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": []
}
POST/api/v1/channels/configs/{config_id}/connected-mailbox/reconnect

Reconnect 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

NameTypeDescription
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.

GET/api/v1/channels/addresses

List 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

NameTypeDescription
channel_type
stringFilter by config channel type (e.g. email)
direction
stringFilter by direction: send, receive, or both
sendable
booleanWhen true, only active send/both addresses on verified configsDefault: false
authorized_to_send
booleanWhen true, filter rows by the caller's channels:addresses:send permission instead of channels:addresses:viewDefault: false

Response Fields

NameTypeDescription
[]*
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"
  }
]
POST/api/v1/channels/configs/{config_id}/addresses

Create 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

NameTypeDescription
config_id*
string (UUID)Channel config ID

Request Body

NameTypeDescription
address*
stringFull address, e.g. support@mail.example.com (3–320 characters)
display_name
string | nullOptional display name for From headers
direction
stringsend, 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"
}
GET/api/v1/channels/configs/{config_id}/addresses

List Addresses

List all addresses belonging to a single channel config.

Bearer token required.

Path Parameters

NameTypeDescription
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"
  }
]
GET/api/v1/channels/addresses/whatsapp/outbound

List 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

NameTypeDescription
limit
integerPage size (default 100, max 200)
offset
integerPagination offset (default 0)

Response Fields

NameTypeDescription
items*
AddressResponse[]WhatsApp addresses the caller may send from
total*
integerTotal 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
}
GET/api/v1/channels/addresses/{address_id}/whatsapp/send-options

Get 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

NameTypeDescription
address_id*
string (UUID)WhatsApp address ID

Query Parameters

NameTypeDescription
to*
stringRecipient phone number in E.164 format
limit
integerTemplate page size (default 100, max 200)
offset
integerTemplate pagination offset (default 0)

Response Fields

NameTypeDescription
free_form_allowed*
booleanTrue when the 24-hour session window with this recipient is open
session_expires_at*
string (ISO 8601) | nullWhen the open session window closes, if one exists
items*
WhatsAppTemplateResponse[]Approved, active utility templates enabled for this address
total*
integerTotal 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
}
PATCH/api/v1/channels/addresses/{address_id}/whatsapp/contacts/{wa_id}/marketing-policy

Update 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

NameTypeDescription
address_id*
string (UUID)WhatsApp address ID
wa_id*
stringWhatsApp contact ID (phone-derived)

Request Body

NameTypeDescription
opted_out*
booleanTrue to opt the contact out of marketing sends

Response Fields

NameTypeDescription
wa_id*
stringWhatsApp contact ID
opted_out*
booleanCurrent 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"
}
PATCH/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

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Request Body

NameTypeDescription
display_name
string | nullNew display name
direction
string | nullsend, receive, or both
status
string | nullAddress status slug (e.g. active, disabled)
receive_enabled
boolean | nullConnected 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"
}
DELETE/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

NameTypeDescription
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 Content

Mailbox

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.

GET/api/v1/channels/addresses/{address_id}/mailbox/messages

Search 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

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Query Parameters

NameTypeDescription
from_address
stringSender address
from_domain
stringSender domain
to_address
stringRecipient address
to_domain
stringRecipient domain
subject
stringText in the subject
text
stringText anywhere in the message
unread
booleanOnly unread (true) or read (false) mail
has_attachment
booleanOnly mail with attachments
received_after
string (date-time)Received at or after
received_before
string (date-time)Received before
label
stringGmail label or Microsoft folder or category
query
stringProvider search syntax (Gmail search or Microsoft KQL), added as is
limit
integerPage size, 1 to 100 (default 25)
page_cursor
stringnext_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
}
GET/api/v1/channels/addresses/{address_id}/mailbox/message

Get Mailbox Message

Read one message with its text, HTML and attachment list.

Bearer token required.

Path Parameters

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Query Parameters

NameTypeDescription
message_id*
stringMailbox 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 }
  ]
}
GET/api/v1/channels/addresses/{address_id}/mailbox/thread

Get Mailbox Thread

Read every message of a mailbox conversation.

Bearer token required.

Path Parameters

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Query Parameters

NameTypeDescription
thread_id*
stringthread_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." }
  ]
}
GET/api/v1/channels/addresses/{address_id}/mailbox/attachments

List Mailbox Attachments

List a message's attachments without downloading them.

Bearer token required.

Path Parameters

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Query Parameters

NameTypeDescription
message_id*
stringMailbox 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 }
  ]
}
POST/api/v1/channels/addresses/{address_id}/mailbox/attachments/save

Save 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

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Request Body

NameTypeDescription
message_id*
stringMailbox message id from Search Mailbox Messages
bucket_id*
stringBucket to save into
folder_id
string | nullFolder in the bucket
attachment_ids
string[] | nullAttachments 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" }
  ]
}
POST/api/v1/channels/addresses/{address_id}/mailbox/message/modify

Modify Mailbox Message

Mark a message read or unread, archive it, or add and remove labels (Gmail) or categories (Microsoft).

Bearer token required.

Path Parameters

NameTypeDescription
address_id*
string (UUID)Connected-mailbox address ID

Request Body

NameTypeDescription
message_id*
stringMailbox message id from Search Mailbox Messages
mark_read
boolean | nulltrue marks it read, false marks it unread
archive
booleantrue 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.

POST/api/v1/channels/send

Send 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

NameTypeDescription
channel
stringChannel to use; currently only emailDefault: email
address_id*
string (UUID)Sending address ID
config*
objectChannel-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 | nullCalling service slug for grant checks (e.g. workflows)
resource_id
string | nullExternal resource ID for grant checks

Response Fields

NameTypeDescription
status*
stringTypically queued
channel*
stringChannel used
log_id
string | nullActivity log row ID for tracking the send
provider_id
string | nullProvider slug handling delivery
provider_message_id
string | nullOutbound SMTP Message-ID set on the email, used for reply correlation
thread_id
string | nullChannel thread ID for the outbound message
idempotent_replay
booleanTrue 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
}
POST/api/v1/channels/send/whatsapp

Send 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

NameTypeDescription
channel*
"whatsapp"Channel discriminator
address_id*
string (UUID)Send-capable WhatsApp address the message goes out from
config*
WhatsAppTextConfig | WhatsAppTemplatePayload | WhatsAppMediaPayload | WhatsAppInteractivePayloadDiscriminated by `type` (text | template | media | interactive); every variant carries `to` in E.164 format
service_name
stringOriginating 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.

GET/api/v1/channels/configs/{config_id}/whatsapp/templates

List 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

NameTypeDescription
config_id*
string (UUID)WhatsApp business-account config ID

Query Parameters

NameTypeDescription
limit
integerPage size (default 100, max 200)
offset
integerPagination offset (default 0)

Response Fields

NameTypeDescription
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*
integerTotal 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
}
POST/api/v1/channels/configs/{config_id}/whatsapp/templates/sync

Sync 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

NameTypeDescription
config_id*
string (UUID)WhatsApp business-account config ID

Response Fields

NameTypeDescription
items*
WhatsAppTemplateResponse[]The synchronized template list
total*
integerTotal 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
}
POST/api/v1/channels/configs/{config_id}/whatsapp/templates

Create 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

NameTypeDescription
config_id*
string (UUID)WhatsApp business-account config ID

Request Body

NameTypeDescription
name*
stringTemplate name: lowercase letters, digits, and underscores (max 512)
language*
stringMeta language code such as pt_BR or en_US
category*
stringUTILITY or MARKETING
parameter_format
stringPOSITIONAL ({{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

NameTypeDescription
id*
string (UUID)Local template ID
status*
stringMeta 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"
}
DELETE/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

NameTypeDescription
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 Content
HTTP/1.1 204 No Content
PUT/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

NameTypeDescription
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 Content
HTTP/1.1 204 No Content
DELETE/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

NameTypeDescription
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 Content
HTTP/1.1 204 No Content

Activity

Inspect the channel type registry, paginated message activity (company-wide or per channel), single events, inbound attachment bytes, and ordered thread transcripts.

GET/api/v1/channels/channel-types

List Channel Types

Registry of channel implementations (slug, display name, icon, active flag).

Bearer token required.

Query Parameters

NameTypeDescription
include_inactive
booleanInclude types marked inactiveDefault: false

Response Fields

NameTypeDescription
[]*
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
  }
]
GET/api/v1/channels/companies/{company_id}/activity

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
channel
stringFilter by channel slug
direction
stringFilter by message direction
status
stringComma-separated status slugs
correlation_id
stringMatch a correlation ID
event_type
stringFilter by event type slug
search
stringCase-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
integerPage number (1-based)Default: 1
limit
integerPage size (1–100)Default: 50

Response Fields

NameTypeDescription
items*
ActivityLogListItem[]id, event_type, channel, direction, from_address, to_addresses, subject, status, actor_type, error, created_at, optional correlation_id and summary
total*
integerTotal matching rows
page*
integerCurrent page
limit*
integerPage 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
}
GET/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

NameTypeDescription
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"
}
GET/api/v1/channels/configs/{config_id}/activity

List 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

NameTypeDescription
config_id*
string (UUID)Channel config ID

Query Parameters

NameTypeDescription
direction
stringFilter by message direction
status
stringComma-separated status slugs
correlation_id
stringMatch a correlation ID
event_type
stringFilter by event type slug
search
stringCase-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
integerPage number (1-based)Default: 1
limit
integerPage size (1–100)Default: 50

Response Fields

NameTypeDescription
items*
ActivityLogListItem[]Activity rows for this channel
total*
integerTotal matching rows
page*
integerCurrent page
limit*
integerPage 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
}
GET/api/v1/channels/configs/{config_id}/activity/consumptions

List 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

NameTypeDescription
config_id*
string (UUID)Channel config ID

Query Parameters

NameTypeDescription
subscription_id
string (UUID)Return deliveries for one stable subscription
status
"pending" | "claimed" | "acked" | "failed"Filter by delivery state
direction
stringFilter the joined event by direction
event_status
stringFilter the joined immutable event status
search
stringMatch event type, sender, or subject
page
integerPage number (1-based)Default: 1
limit
integerPage size (1–100)Default: 50

Response Fields

NameTypeDescription
items*
ActivityConsumptionListItem[]Event summary plus subscription, status, attempts, consumer, and delivery timestamps
total*
integerTotal matching rows
page*
integerCurrent page
limit*
integerPage 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
}
GET/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

NameTypeDescription
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"
}
POST/api/v1/channels/configs/{config_id}/activity/claims

Claim 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

NameTypeDescription
config_id*
string (UUID)Channel config ID

Request Body

NameTypeDescription
subscription_id*
string (UUID)Stable connector subscription identity
address_id*
string (UUID)Inbox address on this channel whose deliveries to claim
consumer_id*
stringCurrent worker or replica identifier
limit
integerMaximum deliveries to claim (1–100)Default: 10
visibility_timeout_seconds
integerLease duration before redelivery (1–3600)Default: 60
cursor
string | nullOpaque keyset cursor for continuing the current scan; omit it on a new polling pass

Response Fields

NameTypeDescription
items*
ActivityClaimedItem[]Immutable event plus subscription delivery lease
next_cursor*
string | nullCursor after the last claimed immutable event
idempotent_replay*
booleanTrue 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
}
GET/api/v1/channels/configs/{config_id}/activity/{event_id}/attachments/{attachment_id}/file

Download 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

NameTypeDescription
config_id*
string (UUID)Channel config ID
event_id*
string (UUID)Activity log row ID
attachment_id*
stringProvider attachment id (resend_attachment_id)

Response Fields

NameTypeDescription
(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
POST/api/v1/channels/configs/{config_id}/activity/{event_id}/ack

Acknowledge 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

NameTypeDescription
config_id*
string (UUID)Channel config ID
event_id*
string (UUID)Activity event ID

Request Body

NameTypeDescription
subscription_id*
string (UUID)Subscription that owns the delivery
lease_token*
string (UUID)Active token returned by the claim

Response Fields

NameTypeDescription
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*
booleanTrue 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
}
POST/api/v1/channels/configs/{config_id}/activity/{event_id}/nack

Negatively 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

NameTypeDescription
config_id*
string (UUID)Channel config ID
event_id*
string (UUID)Activity event ID

Request Body

NameTypeDescription
subscription_id*
string (UUID)Subscription that owns the delivery
lease_token*
string (UUID)Active token returned by the claim
requeue
booleanReturn to pending instead of marking failedDefault: true
delay_seconds
integerDelay 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
}
GET/api/v1/channels/threads/{thread_id}/messages

List 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

NameTypeDescription
thread_id*
string (UUID)Conversation thread ID

Response Fields

NameTypeDescription
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.

GET/api/v1/channels/addresses/granted

List 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

NameTypeDescription
service*
stringService slug to match stored grants
resource_id
stringFurther narrow to one external resource
sendable
booleanWhen true, restrict to addresses eligible to sendDefault: false
channel_type
stringFilter by underlying config channel type

Response Fields

NameTypeDescription
[]*
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"
  }
]
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/grants

List Grants

Return the service grants attached to an address.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
POST/api/v1/channels/configs/{config_id}/addresses/{address_id}/grants

Create Grant

Record that an external service may send using this address for a given resource scope.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Request Body

NameTypeDescription
service_name*
stringCalling service slug (1–50 characters)
resource_id
string | nullScoped resource in the calling service
resource_label
string | nullHuman-readable resource label
label
string | nullOptional 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"
}
DELETE/api/v1/channels/grants/{grant_id}

Revoke Grant

Revoke a service grant by ID.

Bearer token required.

Path Parameters

NameTypeDescription
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 Content

Address 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.

GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl

List Address ACL

List ACL grants for a specific address — the permission grants that control who can use this address.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
POST/api/v1/channels/configs/{config_id}/addresses/{address_id}/acl

Grant 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

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Request Body

NameTypeDescription
principal_type*
stringPrincipal kind: member, api_key, or agent
principal_id*
stringPrincipal identifier
capability
stringsend or receiveDefault: send

Response Fields

NameTypeDescription
id*
stringGrant ID
principal_type*
stringPrincipal kind
principal_id*
stringPrincipal identifier
principal_label*
stringResolved display name
permission_name*
stringPermission slug granted
resource*
stringScoped resource URN
effect*
stringGrant 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"
}
DELETE/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

NameTypeDescription
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
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/eligible-principals

List Eligible Principals

List principals that can be granted ACL on this address, for building a grant picker.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
address_id*
string (UUID)Address ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/eligible

List 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

NameTypeDescription
permission
stringFilter to principals eligible for this permission, such as channels:addresses:receive or channels:addresses:send

Response Fields

NameTypeDescription
[]*
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"
  }
]
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/resource-types

List 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

NameTypeDescription
config_id*
string (UUID)Parent channel config ID
address_id*
string (UUID)Channel address ID

Response Fields

NameTypeDescription
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
  }]
}
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants

List Address Access Grants

List paginated IAM grants scoped to one channel address.

Bearer token with channels:permissions:manage on the address.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Parent channel config ID
address_id*
string (UUID)Channel address ID

Query Parameters

NameTypeDescription
page
integerPage number (1-based)Default: 1
limit
integerPage size (1–500)Default: 100

Response Fields

NameTypeDescription
items*
GrantEntry[]Address-scoped grants
total*
integerTotal grants
page*
integerCurrent page
limit*
integerPage 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
}
POST/api/v1/channels/configs/{config_id}/addresses/{address_id}/access/grants

Create 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

NameTypeDescription
config_id*
string (UUID)Parent channel config ID
address_id*
string (UUID)Channel address ID

Request Body

NameTypeDescription
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 | nullMust equal this address resource when provided
effect
stringGrant 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"
}
DELETE/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

NameTypeDescription
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 Content

Inbound 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.

GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config

Get 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

NameTypeDescription
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) | nullWorkflow 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"
}
GET/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscriber-candidates

List 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

NameTypeDescription
limit
integerPage size (1–500)Default: 100
offset
integerNumber of candidates to skipDefault: 0

Response Fields

NameTypeDescription
items*
InboundSubscriberCandidate[]Same-company users and teams available as subscribers
total*
integerTotal 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
}
PUT/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/handler

Update 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

NameTypeDescription
workflow_entry_phase_id
string (UUID) | nullEntry phase that can create items; null clears the handler

Response Fields

NameTypeDescription
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) | nullWorkflow 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"
}
POST/api/v1/channels/configs/{config_id}/addresses/{address_id}/inbound-config/subscribers

Add 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

NameTypeDescription
principal_type*
"user" | "team"Subscriber identity kind
principal_id*
string (UUID)Canonical principal ID
role*
"observer" | "participant"Conversation membership role

Response Fields

NameTypeDescription
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"
}
PATCH/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

NameTypeDescription
role*
"observer" | "participant"Conversation membership role

Response Fields

NameTypeDescription
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"
}
DELETE/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 Content

Channel 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.

GET/api/v1/channels/configs/{config_id}/access/grants

List Access Grants

Paginated list of access grants on this channel zone.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Query Parameters

NameTypeDescription
page
integerPage number (1-based)Default: 1
limit
integerPage size (1–500)Default: 100

Response Fields

NameTypeDescription
items*
GrantResponse[]id, permission_id, name, resource, effect, is_system, granted_at
total
integerTotal matching rows
page
integerCurrent page
limit
integerPage 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
}
POST/api/v1/channels/configs/{config_id}/access/grants

Create Access Grant

Grant a permission on this channel zone (or a nested resource) to a principal.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Request Body

NameTypeDescription
principal_type*
stringPrincipal kind: member, api_key, agent, or role
principal_id*
stringPrincipal identifier
permission_id*
stringPermission to grant (from List Channel Permissions)
resource
string | nullResource URN to scope the grant to; defaults to the channel zone
effect
stringGrant effectDefault: allow

Response Fields

NameTypeDescription
id*
stringGrant ID
permission_id*
stringPermission granted
name*
stringPermission slug
resource*
stringScoped resource URN
effect*
stringGrant effect
is_system*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
GET/api/v1/channels/configs/{config_id}/access/permissions

List Channel Permissions

Permissions that can be granted on this channel zone and its resources.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
GET/api/v1/channels/configs/{config_id}/access/resource-types

List 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

NameTypeDescription
config_id*
string (UUID)Channel config ID

Response Fields

NameTypeDescription
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"
    }
  ]
}
GET/api/v1/channels/configs/{config_id}/access/eligible

List Eligible Principals

Principals eligible to receive access on this channel zone, for building a grant picker.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
GET/api/v1/channels/configs/{config_id}/access/connection-requests

List Connection Requests

List requests from other principals asking to connect to this channel zone.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Query Parameters

NameTypeDescription
status
stringFilter by request statusDefault: pending

Response Fields

NameTypeDescription
[]*
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"
  }
]
POST/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/approve

Approve Connection Request

Approve a pending connection request, optionally granting a specific set of permissions.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
request_id*
string (UUID)Connection request ID

Request Body

NameTypeDescription
grant
booleanWhether to grant access on approvalDefault: true
permissions
string[] | nullPermission slugs to grant; defaults to the requested permissions
label
string | nullOptional 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"
}
POST/api/v1/channels/configs/{config_id}/access/connection-requests/{request_id}/reject

Reject Connection Request

Reject a pending connection request with an optional reason.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID
request_id*
string (UUID)Connection request ID

Request Body

NameTypeDescription
reason
string | nullOptional 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"
}
GET/api/v1/channels/configs/{config_id}/access/connections

List Inbound Connections

List active connections where another principal connects to this channel zone.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Channel config ID

Response Fields

NameTypeDescription
[]*
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"
  }
]
DELETE/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

NameTypeDescription
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 Content

Webhooks

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.

POST/api/v1/channels/webhooks/email

Receive 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

NameTypeDescription
<provider payload>*
objectProvider-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 }
GET/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

NameTypeDescription
provider*
"gmail" | "microsoft"Mailbox provider
curl "https://platform.ergondata.ai/api/v1/channels/webhooks/connected-mailbox/microsoft?validationToken=abc123"

Response

200 OK
abc123
POST/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

NameTypeDescription
provider*
"gmail" | "microsoft"Mailbox provider

Request Body

NameTypeDescription
<provider payload>*
objectProvider-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
GET/api/v1/channels/webhooks/whatsapp

Verify 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

NameTypeDescription
hub.mode*
stringMust be "subscribe"
hub.challenge*
stringRandom challenge Meta expects echoed back
hub.verify_token*
stringVerify 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 OK
12345
POST/api/v1/channels/webhooks/whatsapp

Receive 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

NameTypeDescription
<Meta payload>*
objectMeta 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 }
GET/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

NameTypeDescription
webhook_token*
stringPer-config opaque webhook token issued during WhatsApp setup

Query Parameters

NameTypeDescription
hub.mode*
stringMust be "subscribe"
hub.challenge*
stringRandom challenge Meta expects echoed back
hub.verify_token*
stringVerify 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 OK
12345
POST/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

NameTypeDescription
webhook_token*
stringPer-config opaque webhook token issued during WhatsApp setup

Request Body

NameTypeDescription
<Meta payload>*
objectMeta 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.

POST/api/v1/channels/configs/access/grants/batch

Batch 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

NameTypeDescription
operations*
BatchGrantOperation[]One or more grouped operations; maximum 200 expanded grants

Response Fields

NameTypeDescription
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*
objectcreated, 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 }
}
POST/api/v1/channels/addresses/access/grants/batch

Batch 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

NameTypeDescription
operations*
BatchGrantOperation[]BatchCreateGrantsRequest operations (client_ref, principal_type/id, resources, permission_ids, effect); maximum 200 expanded grants

Response Fields

NameTypeDescription
results*
BatchGrantResult[]Ordered partial-success results with primary and side-effect error fields
summary*
objectcreated, 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 }
}