Cohorts

You can target a Cohort in two ways. Your choice determines when Twilio evaluates membership.

Use a Cohort for live audiences that should reflect current membership on every send. Use a Cohort Snapshot when you need a frozen, repeatable audience, for example to resend the same campaign to the same recipients or to preserve an auditable record.

The to array in a POST /v1/Messages request accepts a mix of recipient shapes. Two of them target Cohorts:

1
{
2
  "to": [
3
    { "cohortId": "cmp_cohort_01h9krwprkeee8fzqspvwy6nq8" }
4
  ]
5
}

At send time, Twilio expands the Cohort recipient to every Profile in the Cohort. The 10,000-entry cap on to applies to array length, not to Cohort size — a Cohort can contain many more Profiles than that cap, governed by the Cohorts product.

A cohortId or cohortSnapshotId recipient must be the only entry in the to array. Mixing it with any other recipient, including another Cohort or Cohort Snapshot, returns 400.

When the recipient is a Cohort, a Cohort Snapshot, or a Profile, the variables object supports two layers of templating: Cohort expressions resolve first, then Liquid renders the result into your content.

Cohort expressions resolve values server-side, once per Profile. Wrap each expression in ${...}. The expression body reads from the profile.trait.<Group>.<field> and profile.address.<channel> namespaces. For example:

• ${profile.trait.Contact.firstName}
• ${profile.address.email}

Whitespace inside the braces is optional and ignored, so ${ x } and ${x} are equivalent.

After Twilio resolves the Cohort expressions to strings, it renders your content fields with Liquid. Reference each resolved value with {{ variableName }}. You can use any Liquid filter or control flow supported in a standard Bulk Messaging send. See Personalization for the full Liquid layer.

1
{
2
  "to": [
3
    {
4
      "cohortId": "cmp_cohort_01h9krwprkeee8fzqspvwy6nq8",
5
      "variables": {
6
        "firstName": "${profile.trait.Contact.firstName}"
7
      }
8
    }
9
  ],
10
  "content": {
11
    "text": "Hello {{ firstName | default: 'Valued Customer' }}!"
12
  }
13
}

For each Profile in the Cohort, Twilio resolves ${profile.trait.Contact.firstName} from that Profile's traits, then renders the text field with Liquid. If the trait is missing, the default filter falls back to Valued Customer.

The following limits apply to Cohort expressions in a request:

• Each ${...} expression can contain at most 500 characters.
• A single recipient can reference at most 25 distinct ${...} expressions across all of its variables values.
• A variables value can contain literal text and at most one ${...} expression, for example "Hi ${profile.trait.Contact.firstName}!". Two or more ${...} expressions in the same value are rejected.

Twilio checks these rules synchronously when it receives your request. A violation returns 400 Bad Request, and the send is never queued.

Twilio re-checks the semantic validity of a Cohort expression asynchronously while the Operation runs. This re-check is necessary because the referenced traits or Twilio Memory Store may have changed after the Cohort was created. An invalid expression fails the Operation for the affected recipients, but does not fail the initial POST /v1/Messages request. Track the outcome using the Operation returned in the 202 response. See Operations and Message Tracking.

• Learn how to send a message to a Cohort end to end, with per-Profile personalization.
• See Operations and Message Tracking to track the delivery status of your Cohort send.