Outbound

Set Outbound message tags

Replaces the conversation tags of a message. Conversations that start from the message inherit these tags.

PATCH

/v2/outbound/messages/{outboundMessageId}/tags

curl --request PATCH \
  --url https://do.featurebase.app/v2/outbound/messages/{outboundMessageId}/tags \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-09-03.pulsar' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "welcome-campaign-2026-10-01",
  "revision": 123,
  "tagIds": [
    "6457e3ff70afca5d8c27dccc"
  ]
}
'

{
  "conversationTagIds": [],
  "createdAt": "2026-09-01T09:30:00.000Z",
  "createdBy": "6438a1efda3640f8feb72121",
  "definition": {
    "assignee": {
      "id": "<string>",
      "type": "admin"
    },
    "audience": {
      "all": [
        {}
      ],
      "mode": "dynamic",
      "types": [
        "users"
      ]
    },
    "content": {
      "text": "<string>"
    },
    "name": "<string>",
    "options": {
      "action": "none",
      "allowReplies": true,
      "showAs": "badge"
    },
    "schedule": {
      "cooldown": {
        "interval": 123,
        "unit": "days"
      },
      "endsAt": "2026-10-01T09:00:00Z",
      "frequency": "once",
      "maxSends": 123,
      "recurrence": {
        "type": "weekly",
        "weekDays": [
          123
        ]
      },
      "startsAt": "2026-10-01T09:00:00Z",
      "timeRestriction": "any_time",
      "timeWindows": [
        {
          "dayOfWeek": 123,
          "end": "<string>",
          "start": "<string>"
        }
      ]
    },
    "sender": {
      "id": "<string>",
      "type": "admin"
    },
    "trigger": {
      "all": [
        {}
      ]
    },
    "type": "chat"
  },
  "firstActivatedAt": null,
  "id": "6457e3ff70afca5d8c27dccc",
  "lastActivatedAt": null,
  "object": "outbound_message",
  "revision": 123,
  "scheduleSyncPending": true,
  "state": "draft",
  "updatedAt": "2026-09-03T12:00:00.000Z",
  "updatedBy": "6438a1efda3640f8feb72121"
}

Request Body

tagIds - Array of conversation tag IDs (max 20). Send an empty array to remove all tags

Tags must exist in your organization's shared conversation tag pool. See the Conversation Tags endpoints.

Response

Returns the updated message.

Errors

400 - Invalid message ID or unknown tag ID
404 - Message not found or doesn't belong to your organization

Version Availability

This endpoint is only available in API version 2026-09-03.pulsar and newer.

Optional protections: idempotencyKey enables safe retries; revision on existing campaigns rejects stale changes. Neither is required, and they can be used independently. Without a key, each request is a new operation and does not create an operation receipt; do not blindly retry an uncertain create or send. Without a revision, a change can overwrite a concurrent edit. With a key, keep the exact request on retries. Completed results replay for at least 7 days. Changed input returns idempotency_conflict; a concurrent retry returns operation_pending. For operation_outcome_unknown, inspect the Outbound-Operation-Id receipt before another operation. Schedule synchronization stays durable with or without these fields.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

outboundMessageIdstringrequired

Outbound message ID

Example: 6457e3ff70afca5d8c27dccc

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-09-03.pulsar, 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-09-03.pulsar

Body

idempotencyKeystring

Optional retry protection. Keep the same key and request when retrying. Without a key, each request is a new operation.

Required string length: 8 - 128

Pattern: ^[a-zA-Z0-9_.:-]+$

Example: welcome-campaign-2026-10-01

revisioninteger

Campaign version returned by GET. Optionally send it with a mutation to reject stale changes.

Required range: 0 <= x

tagIdsstring[]required

Workspace tag IDs that replace the current tags

Maximum array length: 20

Response

Success

conversationTagIdsstring[]required

Conversation tag IDs applied to conversations started from this message

createdAtstringrequired

ISO 8601 timestamp when created

Example: 2026-09-01T09:30:00.000Z

createdBystringrequired

Admin ID that created the message

Example: 6438a1efda3640f8feb72121

definitionobjectrequired

Editable definition. A dashboard draft or template can have no survey choices yet. The write and validation endpoints require a complete definition.

Show child attributes

firstActivatedAtstring | nullrequired

When the message first went live or was sent

idstringrequired

Unique identifier

Example: 6457e3ff70afca5d8c27dccc

lastActivatedAtstring | nullrequired

When the message most recently went live or was sent

objectenum<string>required

Object type identifier

Available options: outbound_message

Example: outbound_message

revisionintegerrequired

Campaign version returned by GET. Optionally send it with a mutation to reject stale changes.

Required range: 0 <= x

scheduleSyncPendingbooleanrequired

The schedule is saved. Timer synchronization is queued or pending recovery. It does not require another activation request.

stateenum<string>required

Lifecycle state of the message. Use the state endpoint to change it.

Available options: draft, live, paused, scheduled, suspended, sent

Example: draft

updatedAtstringrequired

ISO 8601 timestamp when last updated

Example: 2026-09-03T12:00:00.000Z

updatedBystringrequired

Admin ID that last updated the message

Example: 6438a1efda3640f8feb72121

Still need help? Ask the team