---
title: "Update subscription"
method: PUT
path: "/apps/{client_id}/subscriptions/{id}"
tags: ["Apps"]
---

# Update subscription

`PUT /apps/{client_id}/subscriptions/{id}`

## Request

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

Updates a subscription previously registered by this user. Requires an authenticated user for that subscription row (same as today); agents authenticated with PAT or stateless agent JWT follow the same rule.

## Path parameters

- `client_id` string, required
- `id` string, required

## Request body

- UpdateSubscriptionPayload
  - `subscriptions` string[]: 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.
  - `webhookURL` string: Webhook URL to send the data
  - `subscription_filters` SubscriptionFilter[]
    - `key` string, required: What is the key to filter the data before sending to the webhook
    - `value` union, required: Must match `operator`: use a string or number for "eq" and "ne"; use a non-empty array only for "in".
      - string
      - number
      - string[]
    - `operator` 'eq' | 'ne' | 'in', required: What is the operator to filter the data
  - `subscription_actions` SubscriptionAction[]: Actions are used only for internal apps. (Not allowed to external apps)
    - `action_id` 'run_ai_prompt' | 'send_channel_message_reminder', required: What is the action to perform
    - `entity_type` 'ai_prompt' | 'channel_reminder': What is the entity_type to perform the action on (required when entity_id is provided)
    - `entity_id` string: What is the entity_id to perform the action on (required when entity_type is provided)
    - `metadata` ActionMetadata
      - `conversation_id` string: The conversation/channel ID where the reminder message should be sent
      - `send_as_bot` boolean: Whether the message should be sent as a bot. If true, bot_user_id should be provided
      - `message` string: The message text to send. Either message or from_message_id must be provided
      - `links` string[]: Array of links to be attached to the message
  - `webhook_headers` object, 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.
  - `scheduler_job_metadata` string: JSON stringified scheduler metadata used for schedule-based subscriptions

## Response `200`

- Subscription
  - `created_at` string, date-time, required: The date and time at which the resource was created.
  - `updated_at` string, date-time, required: The date and time at which the resource was last updated.
  - `id` string, required: The primary key of the resource.
  - `client_id` string, required
  - `user_id` string, required
  - `subscriptions` string[], required: Array of subscription events or triggers (including "schedule" for time-based triggers)
  - `webhookURL` string: Webhook URL to send the data
  - `subscription_filters` SubscriptionFilter[]
    - `key` string, required: What is the key to filter the data before sending to the webhook
    - `value` union, required: Must match `operator`: use a string or number for "eq" and "ne"; use a non-empty array only for "in".
      - string
      - number
      - string[]
    - `operator` 'eq' | 'ne' | 'in', required: What is the operator to filter the data
  - `subscription_actions` SubscriptionAction[]
    - `action_id` 'run_ai_prompt' | 'send_channel_message_reminder', required: What is the action to perform
    - `entity_type` 'ai_prompt' | 'channel_reminder': What is the entity_type to perform the action on (required when entity_id is provided)
    - `entity_id` string: What is the entity_id to perform the action on (required when entity_type is provided)
    - `metadata` ActionMetadata
      - `conversation_id` string: The conversation/channel ID where the reminder message should be sent
      - `send_as_bot` boolean: Whether the message should be sent as a bot. If true, bot_user_id should be provided
      - `message` string: The message text to send. Either message or from_message_id must be provided
      - `links` string[]: Array of links to be attached to the message
  - `webhook_headers` object: Custom HTTP headers forwarded on webhook deliveries for this subscription.

---

[API](https://skmtc.dev/carbonvoice/apis/carbon-voice-api.md) · [All operations](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/revisions/b91c5c845122?raw)