Webhooks · part of Voco integrations
Webhooks integration: let any app ask Voco to ring a customer
The Voco webhook lets any app that can send a web request ask your AI receptionist to ring a customer. Send a phone number and a reason, and Voco rings them in your business name, says why it is calling and records the call, keeping to your opening hours.
Included on every plan, from 39p a minute. Set up in about 10 minutes.
What it does
What does the Voco webhook do?
The Voco webhook turns an event in another app, such as a new repair, a new lead or a finished job, into a phone call from your AI receptionist, with no one at your business having to pick up the phone.
Two fields needed, the rest optional
Send a UK phone number and a reason of up to 120 characters. Add a name, a goal or a message if you like, and Voco looks after the rest.
Says why it is ringing
Voco opens with "I'm calling about" and your reason, so the customer knows straight away.
Keeps to your hours
A request that arrives while you are closed waits, and Voco rings when you next open, never before 8am or after 9pm.
Respects opt-outs
Numbers that asked not to be rung are never called, and one number gets one call at a time.
A clear answer back
Every request is told whether a call was scheduled, when it will ring, and if not, exactly why. Your app can check a call or cancel it at any time.
A private address
Your link is long and random, works like a password, and can be replaced in one click.
How it works
How does a webhook become a phone call?
A webhook becomes a phone call in four steps, usually within a minute when you are open.
- 01
Something happens in your app
A tenant reports a repair, a lead fills in a form, or a job is marked done.
- 02
Your app sends Voco a request
A POST to your private address with the customer's phone number and the reason for the call.
- 03
Voco checks and schedules it
It checks the number is a UK number that may be rung, then books the call for now or your next opening time, and tells your app when it will ring.
- 04
Voco rings and records
Voco calls in your business name, handles the conversation, and the call lands in your dashboard with its recording and summary.
Setup
How do I set up the Voco webhook?
You set up the Voco webhook in about 10 minutes: switch it on, copy your private address, point your other app at it, and send a test to a second phone.
- 01
Switch it on
In Voco, open Settings, then Callbacks, and switch on "Accept call requests from a private address".
- 02
Copy your private address
Voco shows your address with a Copy button. Treat it like a password.
- 03
Point your app at it
In Zapier, add a "Webhooks by Zapier" POST step. In HubSpot, add a "Send a webhook" workflow action. In Google Sheets, paste a short script. Send "phone" and "reason".
- 04
Send a test to a second phone
Use a phone you don't ring your Voco number from. Answer, and hear Voco say your reason. Each number gets one call at a time, so wait for the test to finish, or cancel it, before you send another to the same number.
What you need
- An app that can send a web requestZapier, Make, a HubSpot workflow, or your own code.
- Any Voco planPay as you go or monthly. No extra charge and no plan gating.
- About 10 minutesIncluding a test call to a second phone.
Webhook calls are outbound calls, which are in beta. If you cannot see the setting, ask us to add your account.
Questions about the Webhooks integration
Something else? Ring 0333 043 6661 and ask Voco directly.
In detail
The Webhooks integration in detail
What does a request look like?
Send a POST to your private address with a JSON body of two fields. The phone number can be written any usual UK way, and the reason should follow the words "I'm calling about".
POST https://vocohq.co.uk/api/v1/triggers/{your-private-key}/call
Content-Type: application/json
Accept: application/json
{ "phone": "07700 900123", "reason": "your repair at 12 Alban Crescent" }
What else can a request say?
Only phone and reason are needed. These are optional:
| Field | What it does |
|---|---|
name | Who the call is for. Voco checks it is them before it says why it is ringing. |
address, reference, details | What your app knows. Voco confirms these with them instead of asking from scratch, and never reads out a reference unless they ask. |
goal | What to find out, such as "Could the plumber come on Thursday morning?". A short question is asked as the call's first question. |
message | What to tell them, such as "The part has arrived." Voco passes it on in its own words. Up to 300 characters. |
outcomes | Up to 6 short answers you want back, such as "booked", "not now" or "not interested". The result says which one the call reached. |
cancel_if_they_ring_in | true or false. Whether the call is cancelled if they ring you before Voco calls. Leave it out to use your setting. |
What does Voco send back?
Voco answers every request with JSON. A request it accepts says whether a call was scheduled, and why not when it was not, in scheduled and reason. A request it cannot accept, such as a missing field or too many in a minute, carries a message instead.
| Status | Meaning |
|---|---|
| 202 | Scheduled. The reply carries the call's reference in callback and when it will ring in rings_at. |
| 200 | already_scheduled, with scheduled false: a call to that number is waiting, ringing or waiting to try again. The reply carries its reference, status and next_attempt_at. |
| 200 | opted_out: the person asked not to be called, so Voco won't ring them. |
| 402 | low_balance: not rung, to keep your remaining calls free for customers ringing in. You'll see this when your plan is down to its last fifth of calls, or your pay-as-you-go balance is under £10. |
| 404 | The address is unknown, or the setting is switched off. |
| 403 | The account is not active, or is no longer in the beta for outbound calls. |
| 422 | The number is not a UK number Voco may ring, or a field is missing, named in errors. |
| 429 | The daily limit of 50 calls is reached, or more than 30 requests arrived in a minute. Wait for the Retry-After seconds, which for the daily limit run to UK midnight. |
| 503 | Busy for a moment. Try again after the Retry-After seconds. |
How do I check or cancel a call?
Use the reference from the 202 reply. A GET says where the call has got to: its status, attempts, next_attempt_at and, once it is over without ringing, skip_reason. A DELETE cancels it before it rings. Asking twice is fine. A call already ringing or finished answers 200 with cancelled false and the reason.
GET https://vocohq.co.uk/api/v1/triggers/{your-private-key}/calls/{reference}
DELETE https://vocohq.co.uk/api/v1/triggers/{your-private-key}/calls/{reference}
What happens if nobody answers?
Voco tries again as your callback settings say, 30 minutes later by default. While it waits to try again, the call counts as still on its way, so another request for that number is answered already_scheduled. Calls nobody answers are free.
What does Voco send when the call is done?
Add a result address in Settings, then Callbacks, and Voco posts how each call went, signed with your private address: status, skip_reason when it never rang, attempts, the outcome and a short note when you sent outcomes, and the call itself with its summary and whether they booked. mood says how they sounded: calm, rushed, annoyed or confused, or null when nobody was reached.
What does the customer hear?
Voco checks it is talking to the right person when you sent a name, introduces itself by your receptionist's name as the AI assistant for your business, then says "I'm calling about" followed by your reason, for example "I'm calling about your repair at 12 Alban Crescent", and checks it's a good time. From there it handles the call as your receptionist would, and the recording, transcript and summary appear in your dashboard.
How do I test it safely?
Test with a second phone, not the one you ring your Voco number from: if that number rings your Voco line while the test is waiting, the call may be cancelled. Saying "stop calling me" or "I never asked for this" on a test call marks the number as opted out. The account owner can undo that with "Allow calls again" on that customer's page.
Other integrations
Answers at 2am. Charges by the second.
Hear Voco answer a call
Ring 0333 043 6661 and talk to Voco now, or set up your own AI front office today.