New Voco now answers WhatsApp and SMS, sorts your email and follows up for you.
New Voco now answers WhatsApp and SMS, sorts your email and follows up for you. See what's new

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.

Lines of light connecting points across a dark background
Webhooks Call request from Zapier at 09:14Call scheduled
Sent byFixflo, through Zapier
Phone07700 900123
Reasonyour boiler repair at 12 Alban Crescent
Opening lineI'm calling about your boiler repair
RingsNow, you are open until 17:30
Reply202, scheduled

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.

  1. 01

    Something happens in your app

    A tenant reports a repair, a lead fills in a form, or a job is marked done.

  2. 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.

  3. 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.

  4. 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.

  1. 01

    Switch it on

    In Voco, open Settings, then Callbacks, and switch on "Accept call requests from a private address".

  2. 02

    Copy your private address

    Voco shows your address with a Copy button. Treat it like a password.

  3. 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".

  4. 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:

FieldWhat it does
nameWho the call is for. Voco checks it is them before it says why it is ringing.
address, reference, detailsWhat your app knows. Voco confirms these with them instead of asking from scratch, and never reads out a reference unless they ask.
goalWhat to find out, such as "Could the plumber come on Thursday morning?". A short question is asked as the call's first question.
messageWhat to tell them, such as "The part has arrived." Voco passes it on in its own words. Up to 300 characters.
outcomesUp 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_intrue 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.

StatusMeaning
202Scheduled. The reply carries the call's reference in callback and when it will ring in rings_at.
200already_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.
200opted_out: the person asked not to be called, so Voco won't ring them.
402low_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.
404The address is unknown, or the setting is switched off.
403The account is not active, or is no longer in the beta for outbound calls.
422The number is not a UK number Voco may ring, or a field is missing, named in errors.
429The 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.
503Busy 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.

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.

We value your privacy. We use cookies to understand how the site is used, and only after you accept. How we use cookies