Skip to main content

Place a transactional call

A transactional call is placed one at a time, when your system decides, to someone who expects to hear from you: confirming a booking, reading a code, warning about a delay, reminding an appointment. There are three ways to call, from the simplest to the richest:

ModeWhat happens on the lineWhat you get back
Spoken messageA text is read by a synthetic voice.The call outcome (answered, voicemail, no answer…).
Message and keypadThe message asks for a keypad answer: "press 1 to confirm".The outcome and the keys pressed (digits).
AI voice agentAn agent holds a real conversation, within the frame you give it.The outcome and the answers you asked for (result), with a summary.

Keep this API for calls the person is expecting. Prospecting goes through phone campaigns, which handle opt-outs and calling hours.

Prerequisites​

  • The Phone campaign subscription and at least one active campaign number: it is the number shown to the person called.
  • A secret API key with the send_transactional_calls permission, and view_transactional_messages to read calls back. See Authentication.
  • Credits for call minutes (and agent minutes, in agent mode).
  • For agent mode: a voice agent created and published in your account (AI agents › Phone).

1. Read a message​

curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: delivery-delay-20481" \
-d '{
"to": "+33612345678",
"message": "Hello, this is Le Bistrot du Port. Your order will be fifteen minutes late. Thank you for your patience.",
"reference": "order-20481"
}'
FieldRequiredDescription
toyesNumber to call, in international format (+33612345678). A national number is read as French.
messageyes (except agent mode)The text read out, 1,000 characters at most. Write it the way it must be said: "fifteen minutes" rather than "15 min".
fromnoAn active campaign number of your account. Without from, your first campaign number.
voicenoThe synthetic voice: alloy (default), ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse.
repeatnoHow many times the message is read, from 1 (default) to 3. Useful for a code. No effect with gather or agent.
recordnotrue to record the call. The recording can be played from the Metaventus call log.
machine_detectionnoPaid option: recognise an answering machine. See Answering machines.
if_machinenoWith machine_detection: hangup (default) or leave_message.
referencenoYour identifier (booking number…), 128 characters at most. Returned as is, filterable.

Response 202 Accepted: the call is being dialled. Its outcome comes later, by webhook or by reading the message.

{
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33612345678",
"from": "+33221858132",
"body": "Hello, this is Le Bistrot du Port. Your order will be fifteen minutes late. Thank you for your patience.",
"status": "sent",
"reference": "order-20481",
"created_at": "2026-11-11T09:00:00Z",
"sent_at": "2026-11-11T09:00:01Z",
"updated_at": "2026-11-11T09:00:00Z"
}

The message is read as soon as the person answers. The call ends when it has been read.

2. Collect a keypress​

Add gather: the message is read, then the platform waits for keypad input.

curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: booking-48213-confirmation" \
-d '{
"to": "+33612345678",
"message": "Hello, this is Le Bistrot du Port. You booked a table for four on Saturday at 8:30 p.m. Press 1 to confirm, 2 to cancel.",
"reference": "JT-48213",
"gather": {
"valid_digits": "12",
"replies": {
"1": "Thank you, your table is confirmed. See you on Saturday!",
"2": "Noted, your booking is cancelled. Goodbye."
},
"invalid_message": "Sorry, I did not get that. Press 1 to confirm, 2 to cancel.",
"language": "en"
}
}'
gather fieldDefaultDescription
valid_digitsallAccepted keys, among 0123456789*#.
min_digits, max_digits1, 1Input length, up to 16 digits. Beyond one digit, input ends with #, or with * if # is an accepted key.
max_tries2Number of attempts (1 to 5): the message is replayed after invalid input or silence.
timeout_seconds8How long to wait for input, from 1 to 30 seconds.
invalid_message—Sentence read after invalid input, before the next attempt.
replies—One sentence per key, read right after the input: { "1": "Thank you…" }.
default_reply—Sentence read after any valid input that has no dedicated reply. {digits} is replaced by what was typed.
digits_formatdigitsHow {digits} is said: digits (one digit at a time, for a code), time (2030 → "8:30 p.m."), number (2030 → "two thousand thirty").
languagefrThe language used to say {digits} as a time: fr, en, de, es, it, pt, nl, da, sv, fi, pl, ru, ja, ko, zh or hi ("20 h 30", "8:30 p.m.", "20:30 Uhr"…).

Example: ask for a 4-digit arrival time and read it back.

"gather": {
"min_digits": 4,
"max_digits": 4,
"default_reply": "Thank you, we will expect you at {digits}.",
"digits_format": "time",
"language": "en"
}

Typing 2030 makes the platform say "Thank you, we will expect you at 8:30 p.m.", then the call ends. The keys pressed come back in digits.

A second input after a key: followups​

A key can open a second input with its own prompt: "Press 3 to suggest another time", then "Enter the time as four digits". followups maps the key to that second input: message (the prompt, required) and the same fields as gather (min_digits, max_digits, replies, default_reply, digits_format…). The language of gather applies unless the follow-up sets its own. One level only: a follow-up has no followups of its own.

"gather": {
"valid_digits": "123",
"replies": {
"1": "Thank you, the booking is accepted. The guest has been notified.",
"2": "Noted, the booking is declined. The guest has been notified."
},
"followups": {
"3": {
"message": "Enter the time you suggest as four digits, for example 2 0 3 0 for 8:30 p.m.",
"min_digits": 4,
"max_digits": 4,
"digits_format": "time",
"default_reply": "Thank you, we will suggest {digits} to the guest."
}
}
}

The key pressed comes back in digits ("3"), the second input in followup_digits ("2030"). If nothing is entered at the second input, the outcome is no_input.

The closing sentence from your server: reply_url​

To make the sentence the person hears depend on what your system recorded ("Noted, the guest has been notified by text" or "That slot has just been taken"), set reply_url in gather. When the input ends, during the call, the platform sends the keys to that URL and reads, in the same call, the sentence you return.

  • reply_url must be one of your active webhook endpoints (see Events). The request is signed with its secret, like webhooks: headers X-Metaventus-Signature, X-Metaventus-Timestamp, X-Metaventus-Event: voice.input. An unregistered URL is refused when the call is requested (422 reply_url_not_registered).
  • Your server has 5 seconds to answer 200 with {"reply": "…"} (1,000 characters at most); the person waits in silence meanwhile. Allow about one more second for the sentence to be spoken.
  • With no answer in time, an error or an empty reply, the platform reads the sentence set in replies or default_reply. Always provide a fallback sentence.
{
"id": "0b8a6f3e-5d0c-4a43-9a51-1c6a2e7d9f10",
"type": "voice.input",
"created_at": "2026-11-12T18:42:07Z",
"data": {
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33235000000",
"from": "+33221858132",
"reference": "JT-48213",
"digits": "3",
"followup_digits": "2030"
}
}

Expected answer:

{ "reply": "Thank you, we will suggest 8:30 p.m. to the guest. They have been notified by text and e-mail." }

The outcome of the call then reaches you, as always, through the voice.delivered (or voice.failed) event.

3. Hand the call to a voice agent​

With agent, an AI voice agent holds the conversation: it states why it is calling, answers questions, copes with hesitation and changes of mind, then returns the answers you asked for, in a shape your system can process.

curl https://api.metaventus.com/v1/transactional/calls \
-H "X-API-Key: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: booking-48213-agent" \
-d '{
"to": "+33612345678",
"reference": "JT-48213",
"machine_detection": true,
"if_machine": "leave_message",
"message": "Hello, this is Le Bistrot du Port. We were calling to confirm your booking on Saturday at 8:30 p.m. You can manage it from your booking text message. Have a nice day.",
"agent": {
"id": "bbcc3932-f819-4517-9135-760a4c3ea665",
"context": "Customer: Mr Dupont. Restaurant: Le Bistrot du Port, Rouen. Booking: Saturday 15 November 2026 at 8:30 p.m., for 4 people. Reference: JT-48213.",
"first_message": "Hello, this is the Bistrot du Port assistant. I am calling about your booking.",
"result_fields": [
{
"name": "decision",
"type": "enum",
"values": ["confirmed", "cancelled", "reschedule_requested", "no_decision", "wrong_person"],
"required": true,
"description": "The customer decision: confirmed, cancelled, reschedule_requested (wants another time), no_decision (does not decide), wrong_person (not the right person)."
},
{ "name": "new_date", "type": "date", "description": "Only if reschedule_requested: the requested day." },
{ "name": "new_time", "type": "time", "description": "Only if reschedule_requested: the requested time." },
{ "name": "party_size", "type": "number", "description": "Number of people, only if it changes." },
{ "name": "comment", "type": "text", "description": "Any useful detail given by the customer (allergy, expected delay…)." }
]
}
}'
agent fieldRequiredDescription
idyesThe id of a published voice agent of your account. Its voice, language, knowledge base and outbound role apply.
contextyesWhat the agent must know and do for this call: who it calls, about what, with which data (date, time, amount…), and any call-specific instruction. 4,000 characters at most.
first_messagenoIts first sentence, said as soon as the person answers (1,000 characters at most). Without it, the one set for its outbound calls; otherwise it introduces itself.
result_fieldsnoThe answers to return, 15 fields at most (see below).

With agent, message becomes optional: it is the text left on an answering machine. gather and repeat are not used.

Expected answers: result_fields​

Each field describes an answer the agent must get from the person:

PropertyDescription
nameThe field name in result: lowercase letters, digits and _, 40 characters at most. summary is reserved.
typetext (default), boolean, number, enum, date (returned as YYYY-MM-DD) or time (returned as HH:MM, 24-hour).
valuesFor enum: the allowed values (at least two). The agent picks one.
requiredtrue: the agent must fill it in (with your "no answer" value if you have one).
descriptionWhat the field must contain. This is the agent's instruction: be precise, and explain each enum value.

The agent never fills in a field the person did not give: it is simply absent from result. result always contains a summary, a one-sentence summary of the call, in the language of the conversation.

"result": {
"decision": "reschedule_requested",
"new_date": "2026-11-13",
"new_time": "20:00",
"summary": "The customer asks to move the booking to Friday 13 November 2026 at 8 p.m.; the restaurant must check and confirm by text message."
}

If the person changes their mind during the call, the agent updates its answers: you only receive the final version.

What the agent does​

  • It speaks as soon as the person answers: no silence after "hello".
  • It stays on the purpose of the call. For anything else, it says your team will get back to the person.
  • It only promises what your context allows. For a new time, it records the request and announces a later confirmation, without guaranteeing availability.
  • If it is not the right person, it apologises without revealing anything about the call.
  • It ends with a recap and a closing sentence, then hangs up.

Writing a good context​

  • Give the facts of the call, not the agent's role: the role is set once in its profile (AI agents › Phone › Outbound call).
  • Write full dates and times ("Saturday 15 November 2026 at 8:30 p.m."): the agent knows today's date and works out "tomorrow" or "next Friday".
  • Say what it may or may not accept: "The restaurant is full on Sunday", "Do not offer a refund".
  • Only put in context what the person called is allowed to hear.

Answering machines and voicemail​

An answering machine picks up like a person. Two settings decide what happens:

SettingSpoken message or keypadVoice agent
Without machine_detectionThe message is read as soon as the call is answered, to a person or a machine. Outcome: answered.The agent speaks as soon as the call is answered. If it recognises a voicemail, it asks nothing: it leaves a short message (your message if provided), then hangs up. Outcome: voicemail_left, or machine if it could not say anything.
machine_detection: trueThe platform waits for its verdict (2 to 3 seconds) before reading the message. On a machine: if_machine: hangup hangs up (outcome machine), leave_message leaves message after the beep (outcome voicemail_left).The agent speaks as soon as the call is answered, while detection keeps running. On a machine, the agent is cut off, then if_machine applies as for a message. Those few seconds are not counted as agent minutes.

We recommend machine_detection for agent calls: the outcome is reliable, and no agent minute is spent on a voicemail.

Follow the call​

By webhook​

Subscribe an endpoint of your server to call events (see Events):

EventWhen
voice.sentThe call is being dialled.
voice.deliveredThe message was heard: the person answered (answered) or the message was left on their voicemail (voicemail_left).
voice.failedThe call did not succeed: see outcome.
{
"id": "8810d4d4-7933-4e3d-8dd6-281cc280c13b",
"type": "voice.delivered",
"created_at": "2026-11-11T09:01:05Z",
"data": {
"id": "62f2bc4a-ec20-4db2-ada8-32165985a1ed",
"channel": "voice",
"to": "+33612345678",
"from": "+33221858132",
"status": "delivered",
"outcome": "answered",
"digits": "",
"duration_seconds": 57,
"reference": "JT-48213",
"result": {
"decision": "cancelled",
"summary": "The customer cancels the booking of Saturday 15 November 2026 at 8:30 p.m. for 4 people."
},
"sent_at": "2026-11-11T09:00:01Z",
"delivered_at": "2026-11-11T09:01:05Z"
}
}

By reading the call​

curl https://api.metaventus.com/v1/transactional/messages/62f2bc4a-ec20-4db2-ada8-32165985a1ed \
-H "X-API-Key: YOUR_SECRET_KEY"

The response carries the same fields: status, outcome, digits, followup_digits, duration_seconds and result. Calls are listed with text messages and e-mails on GET /v1/transactional/messages (filters status, reference, to).

Outcomes​

outcomeMeaningstatus
answeredThe person answered and heard the message, or spoke with the agent.delivered
voicemail_leftThe message was left on the answering machine.delivered
no_inputThe person answered but pressed no valid key (keypad mode).failed
machineAn answering machine or a phone menu answered, and nothing was left.failed
no_answerNobody answered.failed
busyThe line was busy.failed
rejectedThe call was rejected.failed
failedThe call could not go through.failed

For a failed call, error_code repeats the outcome and error_message explains it. duration_seconds counts from the moment the call was answered.

Billing​

  • Call minutes: counted per started minute, at the destination rate, like your phone campaigns (for example €0.06 excl. VAT per minute to a French landline). A call that is not answered is not billed.
  • Answering-machine detection (machine_detection): €0.01 excl. VAT per call where it is requested.
  • Voice agent: the minutes during which the agent talks to a person are counted as agent minutes, on top of call minutes, at your account's voice-agent rate (pay-as-you-go or from an hour pack, in Settings › Credits).

Before dialling, the platform checks that your credits cover at least one minute to that number; otherwise the call is refused (402 insufficient_credits) and nothing is billed.

Concurrent calls​

Your transactional calls share the concurrent calls of your Phone campaign plan with your campaigns. When they are all busy, a new call is refused (429 concurrent_limit_reached): retry a few seconds later, with the same Idempotency-Key. To get more, add the "Concurrent calls" option to your subscription.

Never call twice​

Send an Idempotency-Key header unique to each call. If your request times out and you replay it with the same key, the first call is returned with a 200 and the header Idempotent-Replayed: true: nobody is called again, nothing is billed again. Reusing a key for a different call is refused (422 idempotency_key_reused).

Refusals​

A refused call is neither dialled nor billed. The body carries a stable code and an explanation in error.

StatuscodeCauseWhat to do
400invalid_to, invalid_message, message_too_long, invalid_reference, invalid_if_machineInvalid requestFix it
400machine_detection_requiredif_machine without machine_detectionAdd machine_detection: true
400invalid_callInvalid gather or agent (the message names the field)Fix it
400invalid_reply_urlgather.reply_url is not an https:// URLFix it
422reply_url_not_registeredgather.reply_url is not one of your active webhook endpointsRegister it, or fix it
402insufficient_creditsNot enough credits for one minute to that numberTop up, then retry
403subscription_requiredNo Phone campaign subscriptionSubscribe
422no_campaign_numberNo active campaign numberAdd a campaign number
422from_not_allowedfrom is not an active campaign number of the accountFix from or remove it
422idempotency_key_reusedKey already used for another callNew key
429concurrent_limit_reachedAll concurrent calls of the plan are busyRetry in a moment
502call_not_placedThe call could not be placedRetry with the same Idempotency-Key
503temporarily_unavailableTemporary incidentRetry with the same Idempotency-Key

No code: from a workflow​

Metaventus automation workflows offer the Place a call action: spoken message and keypad input, with the same options, triggered by an event in your account (appointment booked, order, stage change…).