Channel Manager

Manage workspace communication channel setup and use case provisioning.

Channel Manager exposes workspace-scoped endpoints for channel use cases. Use cases bind a channel to an approved setup and define how that channel is used by services. Channels in internal preview (email, SMS, iMessage, WhatsApp) require enablement by the Amigo team before they can be provisioned - see Channels.

Supported Channels

Channel

Description

outbound_voice

Outbound phone calls

inbound_voice

Inbound phone calls

ringless_voicemail

Voicemail drops without ringing the recipient

email

Outbound and inbound email

Email sending-domain setups are managed by the Amigo team rather than provisioned through the API. Email use cases reference an Amigo-provisioned setup by setup_id.

Use Cases

A use case binds a communication channel to an approved setup. Use cases are provisioned by the Amigo team as part of channel enablement; through the Platform API you can list them, manage which workspace owns them, and bind them to services.

List Use Cases

Supports filtering by entity_name, channel, and setup_id.

List channel use cases

get

List use cases with optional filters by entity_name, channel, setup_id. Requires Channel.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

entity_namestring · nullableOptional

channelstring · enum · nullableOptionalPossible values:

setup_idstring · uuid · nullableOptional

Responses

200

Successful Response

application/json

403

Insufficient permissions.

422

Validation Error

application/json

get/v1/{workspace_id}/use-cases

GET /v1/{workspace_id}/use-cases HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "channel": "text",
      "entity_name": "text",
      "name": "text",
      "description": "text",
      "setup_id": "text",
      "configuration_set_name": "text",
      "sender_email_address": "text",
      "email_type": "text",
      "tier": "text",
      "unsubscribable": true,
      "accepts_cold_inbound": true,
      "created_at": "2026-07-10T21:52:02.192Z",
      "updated_at": "2026-07-10T21:52:02.192Z"
    }
  ]
}

Use Case Ownership

Ownership records which workspace a provisioned use case belongs to. Claiming ownership is idempotent: re-claiming a use case the workspace already owns returns 200. Claiming returns 404 if the use case does not exist and 409 if another workspace already owns it. Releasing ownership returns 204, refuses with 409 while any service still binds the use case (unbind first), and returns 404 if the workspace does not own it. Claiming and releasing require the Channel.ManageOwnership permission (admin tier); reading ownership requires Channel.view.

Assign ownership of a use case to this workspace

put

Claim ownership of a channel-manager use case for the current workspace. Idempotent — re-assigning an already-owned use case returns 200. 404 if the use case does not exist in channel-manager. 409 if the use case is already owned by another workspace. Requires Channel.ManageOwnership permission (admin tier).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

workspace_idstring · uuidRequired

403

Insufficient permissions.

404

Use case not found.

409

Use case is owned by another workspace.

422

Validation Error

application/json

put/v1/{workspace_id}/use-cases/{use_case_id}/ownership

PUT /v1/{workspace_id}/use-cases/{use_case_id}/ownership HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

Check whether this workspace owns a use case

get

Return the ownership record if the current workspace owns the use case, or 404 if it does not (no existence leak). Requires Channel.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

workspace_idstring · uuidRequired

403

Insufficient permissions.

404

Use case not found.

422

Validation Error

application/json

get/v1/{workspace_id}/use-cases/{use_case_id}/ownership

GET /v1/{workspace_id}/use-cases/{use_case_id}/ownership HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

Release this workspace's ownership of a use case

delete

Release the current workspace's ownership of a use case. Refuses (409) while any service still binds the use case — call DELETE /use-cases/{id}/service-binding first. 404 if this workspace does not own the use case. Requires Channel.ManageOwnership permission (admin tier).

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

204

Successful Response

No content

403

Insufficient permissions.

404

Use case not found.

409

Use case is bound to a service; unbind it first.

422

Validation Error

application/json

delete/v1/{workspace_id}/use-cases/{use_case_id}/ownership

DELETE /v1/{workspace_id}/use-cases/{use_case_id}/ownership HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List use cases this workspace owns

get

Return the ids of the channel-manager use cases this workspace owns. Requires Channel.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

itemsstring · uuid[]Required

403

Insufficient permissions.

get/v1/{workspace_id}/use-cases/ownership

GET /v1/{workspace_id}/use-cases/ownership HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Service Binding

A use case must be bound to a platform service before inbound webhook events can resolve to the workspace and before outbound dispatch can route through it.

Binding uses upsert semantics: rebinding to a different service replaces the prior binding. The API returns 409 if a different use case already binds the same (service, channel) pair, and 404 if the service or use case is missing. Getting a binding returns 404 if the use case is unbound. Unbinding returns 204 No Content, or 404 if the use case is not currently bound. Binding requires Channel.create, getting requires Channel.view, and unbinding requires Channel.delete.

Bind a use case to a platform service

put

Bind this use case to a platform service in the current workspace. PUT semantics — rebinding to a different service replaces the prior binding. Inbound webhook events for the use case will resolve to this workspace; outbound dispatch from the service will route through this use case for its channel. 409 if a different use case already binds the same (service, channel) pair. 404 if the service or use case is missing or belongs to another workspace. Requires Channel.create permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Body

service_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case or service not found.

409

Service already has a different use case bound for this channel.

422

Unsupported use case channel.

502

Channel manager unavailable.

504

Channel manager timed out.

put/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

PUT /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-07-10T21:52:02.192Z",
  "updated_at": "2026-07-10T21:52:02.192Z"
}

Get the service binding for a use case

get

Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

get/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

GET /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-07-10T21:52:02.192Z",
  "updated_at": "2026-07-10T21:52:02.192Z"
}

Unbind a use case from its platform service

delete

Release a use case from its bound service in this workspace. Soft-delete on the binding row. 404 if the use case is not currently bound (covers both 'never bound' and 'already unbound'). Requires Channel.delete permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

use_case_idstring · uuidRequired

Responses

204

Successful Response

No content

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

delete/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

DELETE /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Permissions

Operation

Required Permission

List use cases

Channel.view

Read ownership

Channel.view

Claim / release ownership

Channel.ManageOwnership

Bind a service

Channel.create

Read a service binding

Channel.view

Unbind a service

Channel.delete

PreviousChannels NextCalls

Last updated 18 hours ago

Was this helpful?