Phone and messaging

Numbers, calls, call flows, text messages, WhatsApp and verification.

Scopes for this area: voice:read, voice:write and voice:admin.

90 operations

number

Method	Route	What it does	Level	Command
GET	/numbers	The project's phone numbers.	read	rivier voice number list
GET	/numbers/cost	What the numbers cost this month.	read	rivier voice number cost
GET	/numbers/search	Numbers available to buy.	read	rivier voice number search
POST	/numbers	Ask to buy a number. Nothing is bought: the price is recorded and a signed-in owner or manager confirms it.	write	rivier voice number buy
GET	/numbers/{id}	One number with its agents.	read	rivier voice number get
PATCH	/numbers/{id}	Change a number's settings.	write	rivier voice number update
POST	/numbers/{id}/release	Give a number back.	write	rivier voice number release
POST	/numbers/{id}/suspend	Pause a number.	write	rivier voice number suspend
POST	/numbers/{id}/resume	Resume a number.	write	rivier voice number resume
POST	/numbers/{id}/onboarding/{kind}	Record a carrier onboarding step.	write	rivier voice number onboarding
GET	/numbers/{id}/agents	The agents that answer a number.	read	rivier voice number agents
PUT	/numbers/{id}/agents/{agentId}	Let an agent answer a number.	write	rivier voice number add agent
DELETE	/numbers/{id}/agents/{agentId}	Stop an agent answering a number.	write	rivier voice number remove agent

catalogue

Method	Route	What it does	Level	Command
GET	/voice/catalogue	The voices on offer.	read	rivier voice catalogue list
POST	/voice/catalogue/refresh	Refresh the voice list from the provider.	write	rivier voice catalogue refresh
PUT	/voice/catalogue/{voice}/preview	Store a preview clip for a voice.	write	rivier voice catalogue preview

profile

Method	Route	What it does	Level	Command
GET	/voice/project	The project's voice profile.	read	rivier voice profile project
POST	/voice/project	Propose the project's voice profile.	write	rivier voice profile propose project
POST	/voice/profiles/{id}/submit	Send a voice profile for approval.	write	rivier voice profile submit
POST	/voice/profiles/{id}/approve	Approve a voice profile.	write	rivier voice profile approve
POST	/voice/profiles/{id}/reject	Send a voice profile back.	write	rivier voice profile reject

session

Method	Route	What it does	Level	Command
GET	/voice/sessions	Voice sessions.	read	rivier voice session list
GET	/voice/sessions/{id}	One voice session.	read	rivier voice session get
GET	/voice/sessions/{id}/transcript	The transcript of a session.	read	rivier voice session transcript
POST	/voice/sessions/{id}/end	End a session.	write	rivier voice session end
POST	/voice/sessions/{id}/transfer	Hand a session to a person.	write	rivier voice session transfer

workspace number

Method	Route	What it does	Level	Command
GET	/workspace/numbers	The phone numbers of the workspace.	read	rivier voice workspace number list
GET	/workspace/numbers/available	Numbers available to take.	read	rivier voice workspace number available
POST	/workspace/numbers	Ask to take a number. Nothing is bought until a signed-in owner or manager confirms the price.	write	rivier voice workspace number take
DELETE	/workspace/numbers/{id}	Give a number back.	write	rivier voice workspace number release

phone status

Method	Route	What it does	Level	Command
GET	/phone/status	Whether the phone account is live, in test mode or a mock, and the addresses the carrier calls back on.	read	rivier voice phone status get

phone message

Method	Route	What it does	Level	Command
POST	/phone/messages	Send a text, a picture message or a WhatsApp message. Checks opt-out, agreement, the WhatsApp window, the country's rules and the plan allowance first, and refuses with a plain reason and the next step rather than dropping anything. Marketing needs the person's recorded agreement.	write	rivier voice phone message send
GET	/phone/messages	Recent texts and WhatsApp messages, both ways, with where each one stands.	read	rivier voice phone message list
GET	/phone/messages/{id}	One message and where it stands.	read	rivier voice phone message get

phone conversation

Method	Route	What it does	Level	Command
GET	/phone/conversations	Conversations by person, newest first, with the ones waiting for an answer marked.	read	rivier voice phone conversation list
GET	/phone/conversations/{peer}	Everything said with one person, whether they have agreed to hear from you, and until when a WhatsApp reply can be free text.	read	rivier voice phone conversation get

phone contact

Method	Route	What it does	Level	Command
POST	/phone/opt-in	Record how and where a person agreed to receive messages. Needed before marketing and before a WhatsApp template to someone who has not written first.	write	rivier voice phone contact opt in
POST	/phone/opt-out	Record that a person does not want messages. They stay off the list until they opt back in.	write	rivier voice phone contact opt out
DELETE	/phone/people/{peer}	Remove every message and agreement record held for one phone number.	write	rivier voice phone contact erase

phone sender

Method	Route	What it does	Level	Command
GET	/phone/senders	Everything the project can send from: its numbers, sender names and WhatsApp numbers, and which are ready.	read	rivier voice phone sender list
POST	/phone/senders	Add a sender name or a WhatsApp number. A name that a country wants registered waits until the registration is approved.	write	rivier voice phone sender add
DELETE	/phone/senders/{id}	Remove a sender name or WhatsApp number.	write	rivier voice phone sender remove

phone service

Method	Route	What it does	Level	Command
GET	/phone/services	Messaging services: pools of numbers that send as one, keeping each person with the same number.	read	rivier voice phone service list
POST	/phone/services	Create a messaging service, optionally with numbers already in its pool.	write	rivier voice phone service create
POST	/phone/services/{id}/pool	Put a number into a messaging service's pool.	write	rivier voice phone service add number
DELETE	/phone/services/{id}/pool/{senderId}	Take a number out of a messaging service's pool.	write	rivier voice phone service drop number
DELETE	/phone/services/{id}	Delete a messaging service.	write	rivier voice phone service delete

phone template

Method	Route	What it does	Level	Command
GET	/phone/templates	WhatsApp message templates and whether WhatsApp has approved each.	read	rivier voice phone template list
POST	/phone/templates	Write a WhatsApp template. Placeholders are {{1}}, {{2}}. It cannot be sent until WhatsApp approves it.	write	rivier voice phone template create
POST	/phone/templates/{id}/submit	Send a template to WhatsApp for approval.	write	rivier voice phone template submit
POST	/phone/templates/{id}/refresh	Ask WhatsApp where a template's approval stands.	write	rivier voice phone template refresh
DELETE	/phone/templates/{id}	Delete a template.	write	rivier voice phone template delete

phone number

Method	Route	What it does	Level	Command
GET	/phone/numbers/search	Phone numbers available to buy in a country, with monthly price and what the country requires. Searching costs nothing and buys nothing.	read	rivier voice phone number search

phone purchase

Method	Route	What it does	Level	Command
POST	/phone/purchases	Ask to buy a number. Nothing is bought: this records the price and waits for a person to confirm it.	write	rivier voice phone purchase request
GET	/phone/purchases	Requests to buy a number and how each ended.	read	rivier voice phone purchase list
POST	/phone/purchases/{id}/confirm	Confirm a purchase request: the number is bought and the monthly cost starts. Only a signed-in person can do this.	write	rivier voice phone purchase confirm
POST	/phone/purchases/{id}/decline	Decline a purchase request.	write	rivier voice phone purchase decline

phone registration

Method	Route	What it does	Level	Command
GET	/phone/registrations	What each country asks of a sender (sender names, 10DLC, toll-free verification, DLT), where each registration stands, and what it needs from the owner.	read	rivier voice phone registration list
PUT	/phone/registrations	Record where a registration stands, with the details the owner entered.	write	rivier voice phone registration set

verify service

Method	Route	What it does	Level	Command
GET	/verify/services	The project's verification services: each one is a set of rules for one-time codes (channels, code length, expiry, attempt limits, rate limits, fraud guards).	read	rivier verify services
GET	/verify/services/{id}	One verification service with all its settings.	read	rivier verify service
POST	/verify/services	Create a verification service. Defaults are safe: text, call and email, six digits, ten minutes, five tries, rate limits per destination and network address, premium-rate numbers refused.	write	rivier verify service-create
PUT	/verify/services/{id}	Change a verification service. Existing verifications keep running under the rules they started with.	write	rivier verify service-update
DELETE	/verify/services/{id}	Delete a verification service and its verifications.	write	rivier verify service-delete

verify funnel

Method	Route	What it does	Level	Command
GET	/verify/services/{id}/funnel	How many verifications started, were approved and failed in the last hours, and the conversion share: the first number to read when a service is attacked.	read	rivier verify funnel

verify start

Method	Route	What it does	Level	Command
POST	/verify/services/{id}/verifications	Send a one-time code to a phone number or an email address. channel auto uses the service's order and falls back by itself when a channel fails. Rate limits, fraud guards, opt-outs and the plan's allowance are checked first; a refusal says which rule and what to do. The code itself is never returned (only in the mock, where nothing is sent).	write	rivier verify start

verify check

Method	Route	What it does	Level	Command
POST	/verify/services/{id}/check	Check the code a person typed, by destination or verification id. Answers valid and the status (pending, approved, expired or out of tries); a wrong code leaves the verification pending until the tries run out.	write	rivier verify check

verify attempt

Method	Route	What it does	Level	Command
GET	/verify/verifications	Verifications, newest first: filter by service, status, channel, destination or time. Each shows its send attempts by channel.	read	rivier verify list
GET	/verify/verifications/{vid}	One verification with its status, attempts per channel and why a channel failed.	read	rivier verify get
POST	/verify/verifications/{vid}/cancel	Cancel a pending verification: its code stops working.	write	rivier verify cancel
POST	/verify/verifications/{vid}/fallback	Send the code through another channel (the next one in the service's order, or the one named) when the person did not receive it.	write	rivier verify fallback

lookup number

Method	Route	What it does	Level	Command
GET	/lookup/validate	Check the format of a phone number without a network call: valid or not, why, its country, a readable form, and whether its shape says mobile, toll-free or premium-rate.	read	rivier lookup validate
POST	/lookup/numbers	Look a number up: validity and country are free; line type, carrier, caller name, reachability, SIM swap and pumping risk ask the carrier and use the plan's lookups allowance. Recent answers are reused (cached: true) and cost nothing.	write	rivier lookup number
GET	/lookup/numbers	Lookups already made, newest first; filter by number.	read	rivier lookup list

call settings

Method	Route	What it does	Level	Command
GET	/calls/settings	Voice settings: numbers calls may be placed from, recording (off by default), allowed and refused countries, hourly limit, longest call, quiet hours for marketing calls.	read	rivier calls settings
PUT	/calls/settings	Change the voice settings. Recording cannot be turned on until the project confirms its counsel has read the recording rules.	write	rivier calls settings-set

call flow

Method	Route	What it does	Level	Command
GET	/calls/flows	Call flows: what a line does when a call is answered, as data (say, play, pause, ask for a key or a word, transfer, record with consent, hang up). Each carries the address to give a number so it answers with the flow.	read	rivier calls flows
GET	/calls/flows/{id}	One call flow with its nodes and steps.	read	rivier calls flow
POST	/calls/flows	Create a call flow. It is checked in full first: every node a step names must exist, numbers must be valid, audio must be a public https address, and a recording step must say the call is recorded.	write	rivier calls flow-create
PUT	/calls/flows/{id}	Change a call flow's name or steps.	write	rivier calls flow-update
DELETE	/calls/flows/{id}	Delete a call flow.	write	rivier calls flow-delete

call flow check

Method	Route	What it does	Level	Command
POST	/calls/flows/check	Check a flow without storing it: the problems that stop it, and notes (a language the voice cannot speak yet).	write	rivier calls flow-check

call flow simulate

Method	Route	What it does	Level	Command
POST	/calls/flows/simulate	Walk a call flow without placing a call: give the flow and what the caller presses or says at each question, and get back what the line would say and do, and the question it waits at next. Uses the same checks and routing as a real call.	write	rivier calls flow-simulate

call flow template

Method	Route	What it does	Level	Command
GET	/calls/flows/templates	Ready-made call flows to start from: a greeting with a menu, voicemail, and forwarding during opening hours. Each is a complete flow to adjust and save.	read	rivier calls flow-templates

call

Method	Route	What it does	Level	Command
POST	/calls	Place a phone call that runs a call flow when answered. Refused, with the reason, for an invalid or premium-rate number, a refused country, a number the project may not call from, an opted-out person (marketing), quiet hours (marketing), the hourly limit, or an exhausted plan allowance. Minutes are charged when the call ends.	write	rivier calls place
GET	/calls	The call log, newest first, with status and length: filter by status, direction, a party's number or flow.	read	rivier calls list
GET	/calls/{id}	One call: status, who, how long, minutes charged, what the caller pressed or said, every status change, recordings.	read	rivier calls get
POST	/calls/{id}/hangup	End a call that is ringing or in progress.	write	rivier calls hangup

call recording

Method	Route	What it does	Level	Command
GET	/calls/recordings	Recordings kept, with the call, length, how consent was given and the day each is deleted.	read	rivier calls recordings
DELETE	/calls/recordings/{rid}	Delete a recording at the supplier and from the log.	write	rivier calls recording-delete