Outbound

Set an Outbound message state

Moves a message through its lifecycle using the same rules as the dashboard.

PATCH

/v2/outbound/messages/{outboundMessageId}/state

curl --request PATCH \
  --url https://do.featurebase.app/v2/outbound/messages/{outboundMessageId}/state \
  --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,
  "targetState": "draft"
}
'

{
  "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

targetState - One of draft, scheduled, live, paused or sent

State Rules

live activates a dynamic-audience campaign
sent starts a fixed-audience send; it does not confirm recipient delivery
scheduled requires a future schedule.startsAt
paused stops a live or sent campaign; dynamic campaigns can resume with live
draft cancels a scheduled campaign; scheduled campaigns cannot move directly to paused

The message definition must be complete before it can go live. Invalid transitions return 400.

Permissions

Requires the manage_outbound_state permission.

Response

Returns the message with its new state and activation timestamps.

Errors

400 - Invalid message ID, invalid transition or incomplete content
403 - Your plan does not include this message channel
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

targetStateenum<string>required

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

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