add_campaign_recipients

add_campaign_recipients(campaign_id: str, recipients: list) -> dict

Adds recipients to a continuous phone campaign. Use it in a recurring job, an event handler or a custom action to feed the campaign from your own systems. It does the same as the REST endpoint and needs no API key.

Parameters

Name	Type	Description
`campaign_id`	`str`	The campaign's ID. It must be a continuous campaign of your organization that is a draft, running or paused.
`recipients`	`list`	1 to 10,000 dicts, each with the recipient fields below

Recipient key	Type	Description
`phone`	`str`	Required. E.164 format, e.g. `"+15551234567"`
`name`	`str`	Optional. Spoken in the greeting through `{name}`. Max 500 characters
`context`	`str`	Optional. Free text the AI reads before the call. Max 2,000 characters
`metadata`	`dict`	Optional. JSON for your hooks and actions, never shown to the AI. Max 4 KB
`dedupeKey`	`str`	Optional. A key already used in this campaign, even by a finished call, is skipped forever

Returns

dict: {"added": int, "skippedDuplicates": int}

Behavior

Duplicates are skipped and counted in skippedDuplicates: repeats within the call, numbers already waiting or being called in the campaign, and reused dedupeKeys. See De-duplication.
A number whose earlier call finished can be added again, unless its dedupeKey was used before.
Raises ValueError for a missing campaign_id or an empty list.
Raises requests.HTTPError when the campaign is one-shot, completed or canceled, isn't found, or a recipient is invalid. The response's JSON error says why.

Examples

Call abandoned carts from a recurring job

CAMPAIGN_ID = "00000000-0000-0000-0000-000000000000"

def run_job(context):
    carts = find_abandoned_carts(minutes=60)  # your own lookup
    if not carts:
        return {"added": 0}
    result = add_campaign_recipients(
        CAMPAIGN_ID,
        [
            {
                "phone": cart["phone"],
                "name": cart["first_name"],
                "context": f"Left {cart['items']} in the cart.",
                "metadata": {"cartId": cart["id"]},
                "dedupeKey": f"cart-{cart['id']}",
            }
            for cart in carts
        ],
    )
    return result

The dedupeKey makes sure a cart found again on the next run isn't called twice.