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:
| Mode | What happens on the line | What you get back |
|---|---|---|
| Spoken message | A text is read by a synthetic voice. | The call outcome (answered, voicemail, no answer…). |
| Message and keypad | The message asks for a keypad answer: "press 1 to confirm". | The outcome and the keys pressed (digits). |
| AI voice agent | An 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_callspermission, andview_transactional_messagesto 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"
}'
| Field | Required | Description |
|---|---|---|
to | yes | Number to call, in international format (+33612345678). A national number is read as French. |
message | yes (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". |
from | no | An active campaign number of your account. Without from, your first campaign number. |
voice | no | The synthetic voice: alloy (default), ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse. |
repeat | no | How many times the message is read, from 1 (default) to 3. Useful for a code. No effect with gather or agent. |
record | no | true to record the call. The recording can be played from the Metaventus call log. |
machine_detection | no | Paid option: recognise an answering machine. See Answering machines. |
if_machine | no | With machine_detection: hangup (default) or leave_message. |
reference | no | Your 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 field | Default | Description |
|---|---|---|
valid_digits | all | Accepted keys, among 0123456789*#. |
min_digits, max_digits | 1, 1 | Input length, up to 16 digits. Beyond one digit, input ends with #, or with * if # is an accepted key. |
max_tries | 2 | Number of attempts (1 to 5): the message is replayed after invalid input or silence. |
timeout_seconds | 8 | How 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_format | digits | How {digits} is said: digits (one digit at a time, for a code), time (2030 → "8:30 p.m."), number (2030 → "two thousand thirty"). |
language | fr | The 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_urlmust be one of your active webhook endpoints (see Events). The request is signed with its secret, like webhooks: headersX-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
200with{"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 inrepliesordefault_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 field | Required | Description |
|---|---|---|
id | yes | The id of a published voice agent of your account. Its voice, language, knowledge base and outbound role apply. |
context | yes | What 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_message | no | Its 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_fields | no | The 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:
| Property | Description |
|---|---|
name | The field name in result: lowercase letters, digits and _, 40 characters at most. summary is reserved. |
type | text (default), boolean, number, enum, date (returned as YYYY-MM-DD) or time (returned as HH:MM, 24-hour). |
values | For enum: the allowed values (at least two). The agent picks one. |
required | true: the agent must fill it in (with your "no answer" value if you have one). |
description | What 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
contextallows. 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
contextwhat the person called is allowed to hear.
Answering machines and voicemail
An answering machine picks up like a person. Two settings decide what happens:
| Setting | Spoken message or keypad | Voice agent |
|---|---|---|
Without machine_detection | The 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: true | The 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):
| Event | When |
|---|---|
voice.sent | The call is being dialled. |
voice.delivered | The message was heard: the person answered (answered) or the message was left on their voicemail (voicemail_left). |
voice.failed | The 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
outcome | Meaning | status |
|---|---|---|
answered | The person answered and heard the message, or spoke with the agent. | delivered |
voicemail_left | The message was left on the answering machine. | delivered |
no_input | The person answered but pressed no valid key (keypad mode). | failed |
machine | An answering machine or a phone menu answered, and nothing was left. | failed |
no_answer | Nobody answered. | failed |
busy | The line was busy. | failed |
rejected | The call was rejected. | failed |
failed | The 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.
| Status | code | Cause | What to do |
|---|---|---|---|
400 | invalid_to, invalid_message, message_too_long, invalid_reference, invalid_if_machine | Invalid request | Fix it |
400 | machine_detection_required | if_machine without machine_detection | Add machine_detection: true |
400 | invalid_call | Invalid gather or agent (the message names the field) | Fix it |
400 | invalid_reply_url | gather.reply_url is not an https:// URL | Fix it |
422 | reply_url_not_registered | gather.reply_url is not one of your active webhook endpoints | Register it, or fix it |
402 | insufficient_credits | Not enough credits for one minute to that number | Top up, then retry |
403 | subscription_required | No Phone campaign subscription | Subscribe |
422 | no_campaign_number | No active campaign number | Add a campaign number |
422 | from_not_allowed | from is not an active campaign number of the account | Fix from or remove it |
422 | idempotency_key_reused | Key already used for another call | New key |
429 | concurrent_limit_reached | All concurrent calls of the plan are busy | Retry in a moment |
502 | call_not_placed | The call could not be placed | Retry with the same Idempotency-Key |
503 | temporarily_unavailable | Temporary incident | Retry 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…).