Skip to main content

Example: retries by outcome

Each call outcome can have its own pause before the next dial: an expert logic rule with the retry_in action and the params.interval_s parameter. Below is a ready request and what each part of it does.

The whole request

The campaign is created and launched with one POST /v1/campaigns request.
The answer is 201 with campaign_id, status, blockers and warnings. status: "running" means dialing has started; draft means something blocks it, and the reason is in blockers. The full response is in Creating a campaign.

What each rule does

Each rule is a pair “if outcome → then action”. The interval counts from the end of the call and, for that contact, replaces the campaign interval. The voicemail_reached rule also fires on voicemail_suppressed — voicemail was detected, but leaving a message was not allowed. Every if value is a status_reason code from Call outcomes, plus short_call and goal_not_achieved. An outcome that no rule matches is decided by the general outcome table, as in standard: voicemail without a rule of its own is redialed after the campaign interval_s (Call outcomes). That is why the example has its own voicemail_reached rule; once its max_matches is used up, voicemail is redialed by the general table while dials are left. To stop calling voicemail, use stop_calling.

Rules and limits

  • attempts is the overall cap on dials per contact, the first one included, 1 to 30. Rules do not extend it: when the dials run out, the contact is closed even if a rule has matches left.
  • interval_s of retry_in is whole seconds from 60 to 86400 (1 minute to 24 hours). It is required with retry_in and forbidden with the other actions, otherwise 422 campaign_spec_invalid.
  • max_matches is how many times the rule may fire for one contact, 1 to 30, default 1. short_call has none — sending it there is refused with 422 campaign_spec_invalid.
  • max_duration_s of short_call is required, at least 10 seconds.
  • No retry on a permanent reason. For invalid_destination and spam_blocked on every market, and for user_declined and screener_declined under the US market package, only stop_calling is allowed. On other markets user_declined is temporary and a retry on it is allowed — the example sets stop_calling on purpose.
  • One “condition + action” pair — once. A duplicate is refused.
  • Expert mode without a single rule cannot be launched: the rules_empty blocker.
  • The calling window, the do-not-call registry and the frequency caps apply to every retry. A retry that does not fit before the end of the campaign (ends_at) is not scheduled.
  • The rule_interval_exceeds_end warning means a rule interval is not shorter than the campaign window left: that retry will not happen. It does not block the launch.
  • Do not send a rule id — the server assigns it (r-xxxxxxxx) and returns it in the response.

For dialing to start right away

  • Idempotency-Key is required, a new one for every new campaign. Repeating the request with the same key after a timeout does not create a second campaign.
  • attestation: {"confirmed": true} is the contacts’ consent attestation. Without it the campaign is created as a draft with the attestation_required blocker. See Consent, the registry and who is responsible.
  • The agent is published. Otherwise — a draft with the agent_not_published blocker. agent_id is the agent’s name.
  • The agent has Detect answering machines on. Without it there is no voicemail_reached outcome, and the voicemail rule never fires.
  • Do not send trunk_id, route_id and from_number — the platform finds the line from the agent (Dialing binding).
  • working_hours only narrows the organization’s calling window; a wider row → 422 working_hours_wider_than_law.

See also