For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
get/v1/{workspace_id}/use-cases

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
put/v1/{workspace_id}/use-cases/{use_case_id}/ownership

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
get/v1/{workspace_id}/use-cases/{use_case_id}/ownership

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

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

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
get/v1/{workspace_id}/use-cases/ownership

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
put/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

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
get/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

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

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

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

Last updated

Was this helpful?