Apps

Subscribe user to events sent via webhook

OAuth access token must be issued for this client_id. With a personal access token (PAT), use cv:write and an app you own (client.owner_id matches the authenticated user). With a stateless agent JWT (POST /agents/:id/tokens), the same cv:write rule applies via embedded scopes (cv:read + cv:write). With a session token (pxtoken), ownership of the app is required; no scope is needed.

post/apps/{client_id}/subscribe

Request

  • Base URL: https://api.carbonvoice.app
  • URL: https://api.carbonvoice.app/apps/{client_id}/subscribe
  • Auth: one of:
    • API key in header pxtoken
    • OAuth 2 (implicit, authorization URL https://api.carbonvoice.app/oauth/authorize)

Path parameters

client_idstring required

Request body

subscriptionsstring[]

All events are subscribed by default: message.initializing, message.started, message.paused, message.resumed, message.offline, message.processing, message.finished, message.deleted, message.discussion-notes.added, message.label.added, message.attachment.added, message.attachment.uploaded, message.posted.to.channel, message.voicememo.created, channel.created, channel.deleted, channel.user.joined, channel.users.added, channel.user.left, channel.user.removed, channel.async-check.mid, channel.async-check.ending, channel.async.ended, channel.async.extended, channel.async.shortened, channel.ai-summary.generated, workspace.user.joined, workspace.user.added, workspace.user.left, workspace.user.removed, workspace.findable-channel.created, ai.prompt.response.generated, action-item.created, action-item.updated, action-item.deleted, action-item.status.changed, ask.answered. Also supports 'schedule' trigger for time-based triggers.

webhookURLstring

Webhook URL to send the data

webhook_headersobject nullable

Custom HTTP headers Carbon Voice will forward on every webhook delivery for this subscription. Pass null to clear previously set headers; omit the field to leave existing headers unchanged.

Example request

{
  "subscription_filters": [
    {
      "key": "name",
      "operator": "eq"
    }
  ],
  "subscription_actions": [
    {
      "action_id": "run_ai_prompt",
      "entity_type": "ai_prompt",
      "metadata": {
        "conversation_id": "channel_123",
        "send_as_bot": true,
        "message": "Daily standup reminder!",
        "links": [
          "https://pxassets.s3.us-east-2.amazonaws.com/images/v2/logo.png",
          "https://pxassets.s3.us-east-2.amazonaws.com/images/v2/Personal+CarbonLink.svg",
          "https://www.youtube.com/watch?v=36Tn5cektlg"
        ]
      }
    }
  ],
  "webhook_headers": {
    "x-api-key": "secret",
    "x-version": 2
  }
}

Response

created_atstring date-time required

The date and time at which the resource was created.

updated_atstring date-time required

The date and time at which the resource was last updated.

idstring required

The primary key of the resource.

client_idstring required
user_idstring required
subscriptionsstring[] required

Array of subscription events or triggers (including "schedule" for time-based triggers)

webhookURLstring

Webhook URL to send the data

webhook_headersobject

Custom HTTP headers forwarded on webhook deliveries for this subscription.

Example response

{
  "subscriptions": [
    "message.initializing",
    "message.started",
    "message.paused",
    "message.resumed",
    "message.offline",
    "message.processing",
    "message.finished",
    "message.deleted",
    "message.discussion-notes.added",
    "message.label.added",
    "message.attachment.added",
    "message.attachment.uploaded",
    "message.posted.to.channel",
    "message.voicememo.created",
    "channel.created",
    "channel.deleted",
    "channel.user.joined",
    "channel.users.added",
    "channel.user.left",
    "channel.user.removed",
    "channel.async-check.mid",
    "channel.async-check.ending",
    "channel.async.ended",
    "channel.async.extended",
    "channel.async.shortened",
    "channel.ai-summary.generated",
    "workspace.user.joined",
    "workspace.user.added",
    "workspace.user.left",
    "workspace.user.removed",
    "workspace.findable-channel.created",
    "ai.prompt.response.generated",
    "action-item.created",
    "action-item.updated",
    "action-item.deleted",
    "action-item.status.changed",
    "ask.answered"
  ],
  "subscription_filters": [
    {
      "key": "name",
      "operator": "eq"
    }
  ],
  "subscription_actions": [
    {
      "action_id": "run_ai_prompt",
      "entity_type": "ai_prompt",
      "metadata": {
        "conversation_id": "channel_123",
        "send_as_bot": true,
        "message": "Daily standup reminder!",
        "links": [
          "https://pxassets.s3.us-east-2.amazonaws.com/images/v2/logo.png",
          "https://pxassets.s3.us-east-2.amazonaws.com/images/v2/Personal+CarbonLink.svg",
          "https://www.youtube.com/watch?v=36Tn5cektlg"
        ]
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.