Signals Docs
Automations

Triggering calls

To call one customer, send a POST request to the automation's trigger URL. Copy the URL from the automation's Trigger and credentials tab in the console, which admins and engineers can see. It has the form https://api.signals.pressone.africa/automations/{automation_id}/calls, where the automation id starts with sig_. Both operations on this page are listed in the Automations API reference.

Authentication

Authenticate with an organization API key sent as a Bearer token in the Authorization header. The key must hold the service_configuration:write scope and cannot be restricted to a subaccount. The request runs in the automation's own project, so it does not need an X-Project-ID header. A key that has been revoked or has expired may continue to work for up to 60 seconds. See Authentication to create a key.

The request

The body is a JSON object of at most 16 KiB.

FieldRequiredDescription
phone_numberYesThe number to call, in E.164 format: a + followed by 8 to 15 digits, the first of which is not 0.
nameNoThe customer's name, used for the {{name}} variable. At most 120 characters.
event_idNoYour identifier for this trigger, used for idempotency. At most 120 characters and not blank.
parametersNoValues for the message's other variables, such as time. At most 40 keys. Each key starts with a letter and contains only letters, digits and underscores, up to 64 characters. Each value is a string of at most 500 characters, a number or a boolean.
metadataNoAny JSON object of at most 4096 bytes. Signals stores it with the run and returns it in every webhook event.
TerminalCode
curl -X POST "https://api.signals.pressone.africa/automations/sig_0199c4e2-5a10-7000-8000-000000000017/calls" \ -H "Signals-Version: 2026-10-27" \ -H "Authorization: Bearer $SIGNALS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+2348035550142", "name": "Adebayo Ogundimu", "event_id": "appt-77120-2026-10-30", "parameters": { "time": "10:30" }, "metadata": { "booking": "APPT-77120" } }'
JSONCode
{ "id": "run_0199c4e2-7b1a-7000-8000-000000000042", "signalId": "sig_0199c4e2-5a10-7000-8000-000000000017", "runId": "run_0199c4e2-7b1a-7000-8000-000000000042", "recipientNumber": "+2348035550142", "status": "queued", "outcome": null, "suppressionReason": null, "createdAt": "2026-10-29T09:00:00Z" }

Signals applies the suppression rules before it answers, then responds with the run as it stands, using camelCase field names. id and runId carry the same run id and signalId is the automation id. A run that passed the rules is queued with outcome and suppressionReason still null; a run stopped by a rule already shows status finished, outcome suppressed and the reason; a run that arrived outside calling hours on an automation set to wait shows waiting_hours. A 202 Accepted therefore means Signals accepted the request, not that the call has been placed. Follow the run through its webhook events or the console.

Idempotency

Use event_id to make triggers safe to retry. Signals keeps one run per event_id for each automation. If you send the same event_id again, Signals returns 200 OK with the original run as it is now and does not call the customer a second time.

Derive the event_id from the business event rather than generating it at send time. For an appointment reminder, appt-77120-2026-10-30 identifies one booking on one day, so every retry of that reminder carries the same value. A new UUID per attempt defeats the purpose, because two ids for the same event produce two calls. If you omit event_id, Signals generates one in the form auto_<uuid>, and retrying such a request calls the customer again.

Responses and errors

Error responses use the problem format described in Requests and errors. The code member identifies the reason, and on a 422 response the field member names the invalid field.

StatuscodeMeaningWhat to do
202Signals created a new run.No action is required.
200The event_id matches an earlier trigger, and the body is the original run.No action is required. The customer is not called again.
401unauthenticatedThe API key is missing or not recognised.Check the Authorization header and the key.
403api_key_scope_missingThe key does not hold service_configuration:write.Use a key that has the scope.
403api_key_subaccountThe key is restricted to a subaccount.Use an organization API key.
404automation_not_foundYour organization has no automation with this id.Check the automation id in the trigger URL.
413The body is larger than 16 KiB.Reduce the size of the request body.
422invalid_phone_number, invalid_name, invalid_event_id, event_id_too_long, invalid_parameters, invalid_metadata, metadata_too_large, invalid_bodyA field is invalid. invalid_body means the body was not a JSON object.Correct the field named in field and send the request again.
429rate_limitedThe automation received more than 20 requests in one second. The response carries Retry-After: 1.Wait one second, then retry with the same event_id.
503try_again, identity_unavailableSignals could not store the request or verify the key. A try_again response carries Retry-After: 1.Retry with the same event_id.

Retry 429 and 503 responses, and requests that time out, with the same event_id. Correct the cause of a 401, 403 or 422 before you send the request again.

Suppression rules

Before dialling, Signals checks the automation's rules in the order below and stops at the first one that applies. A run stopped by a rule finishes with outcome suppressed and suppressionReason records the rule. A suppressed run is a deliberate decision not to call, not a failed call. You can switch off the do-not-call, daily-limit and calling-hours rules in step 6 of the builder.

RulesuppressionReason
The automation is switched off.automation_off
The number is on the do-not-call list.do_not_call
The automation has already called this number today, counted in the calling-hours time zone.already_called_today
The trigger arrives outside calling hours and the automation is set not to call outside them. If it is set to wait instead, the run takes the status waiting_hours and is called when calling hours open.outside_hours

Run status

FieldValues
statusstaged, queued, waiting_hours, scheduled, dialing, placed, ringing, answered, finishing, finished
outcomenull until the run finishes, then one of completed, no_answer, busy, suppressed, failed, rejected, expired, duplicate
suppressionReasonnull, or one of automation_off, do_not_call, already_called_today, outside_hours, no_longer_owed

Cancel a run

If a call is no longer needed, for example because the customer rescheduled, cancel the run before Signals dials it. Send a POST request to the trigger URL with /cancel appended, using the same API key, and identify the run by the event_id you triggered it with. Unlike on a trigger, event_id is required here.

TerminalCode
curl -X POST "https://api.signals.pressone.africa/automations/sig_0199c4e2-5a10-7000-8000-000000000017/calls/cancel" \ -H "Signals-Version: 2026-10-27" \ -H "Authorization: Bearer $SIGNALS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_id": "appt-77120-2026-10-30" }'
JSONCode
{ "id": "run_0199c4e2-7b1a-7000-8000-000000000042", "signalId": "sig_0199c4e2-5a10-7000-8000-000000000017", "runId": "run_0199c4e2-7b1a-7000-8000-000000000042", "recipientNumber": "+2348035550142", "status": "finished", "outcome": "suppressed", "suppressionReason": "no_longer_owed", "createdAt": "2026-10-29T09:00:00Z" }

If the run has not been dialled yet, Signals suppresses it and returns it with 200 OK. If it has already been dialled or has finished, Signals returns the run unchanged with 200 OK and does not end a call in progress. If no run of the automation has that event_id, the response is 404 with code event_id_unknown. A missing or invalid event_id returns 422, and the authentication, rate-limit and storage errors match those of a trigger.

Last modified on