Start calls

On Boost, your integration can set up calls between you and a customer: a Call button on a lead in your CRM, a callback from a missed-call report, a follow-up when a job closes. SimpleVox rings your phone, and when you answer it dials the customer from your business number. It’s a normal call between two people, and it shows up in the customer’s conversation like any other call.

There’s no AI on the call. Recording follows the number’s call recording setting, like any other call.

Before you call

• A Boost plan. Calling over the API is part of Boost. See Plans and billing.
• A token with Start assisted calls. Create a personal API token and tick Start assisted calls under Write permissions. Tick End assisted calls too if your integration should cancel or hang up. See Authentication.
• A device that can take the call. The person who owns the token needs SimpleVox open at my.simplevox.app with the browser phone on, or the SimpleVox mobile app with calls allowed, once it’s updated to show these calls.
• A number the token can call from. The token’s person needs access to the number, and the token must include it.
• Allowance or credits. Calls you set up through the API count toward Boost’s monthly allowance of 150 calls per person, shared with your AI tools. Past it, the billing owner buys credits in Settings → Plan & billing. See AI tool and API usage.

How the call connects

1. Your phone rings first. It shows as a call to the customer, not a call from them.
2. When you answer, you hear who’s being called, and your purpose if you sent one.
3. SimpleVox dials the customer from your business number. You hear it ring, and you’re connected when they pick up, as on any call you place. If they don’t, you reach their voicemail.

Nobody presses 1. The customer hears you, not a recording. mode is optional: user_first is the only order, and recipient_first is refused with 422.

Your phone rings for up to 20 seconds and the customer’s for up to 30. Setup has to finish within 90 seconds, and a call can last up to 4 hours. If the customer isn’t reached, you hear why on the call, such as a busy line.

Check calling options

Calling options list the numbers you can call from and calling_devices: the devices that can ring for you, default first. Check them when you need to choose a number or a device, or to make sure one is on before you show a Call button: a browser is listed only while SimpleVox is open with the browser phone on, and the mobile app only while calls are allowed on it. A token without Start assisted calls, or a workspace that isn’t on Boost, gets 403. Reference: List calling options.

Start a call

Send the customer’s number as to, in E.164 format. Reference: Start a call.

• Number. Leave out from and SimpleVox uses the only number available. If there’s more than one to choose from, you get 422 listing the choices; pick one from calling options.
• Device. Leave out user_endpoint_id to ring your default device: the browser phone if it’s on, otherwise the phone you used most recently. To ring another, send its id from calling options. If no device is on, you get 422, and the message for user_endpoint_id says how to turn one on.
• A private reminder. purpose is read to you when you answer, before the customer is dialed, such as “Callback about the furnace estimate”. The customer never hears it.
• The contact. Send contact_id to file the call under a contact. The contact must have the to number.

curl https://api.simplevox.app/v1/assisted-calls \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "to": "+12025550142",
    "contact_id": "9b1f4c2e-3a5d-4e8f-9c71-2d6a8e0b4f13",
    "purpose": "Callback about the water heater install"
  }'

A successful request returns 202 Accepted with the call’s setup. Trimmed:

{
  "data": {
    "id": "1f8c3a6e-9b2d-4e75-a0c4-6d3e8b1f2a97",
    "mode": "user_first",
    "setup_state": "pending",
    "connection_state": "not_verified",
    "communication": {
      "kind": "call",
      "id": "6a4d2c8e-1f7b-4b3a-9e05-c2d8f1a7e364",
      "source_version": 1,
      "url": "https://my.simplevox.app/sources/call/6a4d2c8e-1f7b-4b3a-9e05-c2d8f1a7e364?version=1"
    }
  }
}

202 means SimpleVox saved the call and started setting it up, not that anyone answered. The response has two IDs:

• id identifies this call setup. Use it to follow or end the call.
• communication.id is the call itself, the same ID you’ll see in contact history and when you quote the call or read its recordings and transcript.

The response also has a next_step hint written for AI assistants, which you can ignore.

Follow a call

Poll the call’s setup to show progress in your integration. Reference: Retrieve a call.

• participants shows each side’s progress: whether they’ve answered (accepted), joined and left.
• connection_state becomes verified once the customer’s line answers and you’re connected. That can be their voicemail. connected_observed_at and ended_observed_at record when SimpleVox saw the call connect and end.
• outcome and reason explain how a call that didn’t connect ended, such as a busy line or you not answering in time.
• Treat setup_state, outcome and reason as open-ended strings.

Only the token that started a call can read or end it, and only while the person still has access to its number. A replacement token can’t take over calls an older token started. Reading the status never changes the call.

End a call

Ending a call needs End assisted calls. It cancels a call that’s still being set up, or hangs up a connected one. There’s no body and no Idempotency-Key: ending the same call twice is safe. Reference: End a call.

The response’s action says what SimpleVox did: cancel_setup while the call was still being set up, end_call for a connected call, or already_ended. If it’s connection_observed, the call connected just before your request: check its status, then end it again.

202 means SimpleVox is ending the call, not that it has ended. Poll the status until cleanup is confirmed. Until then, a side of the call may still be on the line.

Closing your integration or your browser tab doesn’t cancel a call. End it through the API, or hang up in SimpleVox.

Retries

Every new call needs an Idempotency-Key. If a request times out or the response is lost, send it again with the same key and the same body. SimpleVox returns the call it already saved, with the same number and device it chose the first time, instead of ringing anyone again.

Caution

Never retry an uncertain call with a new key. A new key is a new call, and your customer’s phone may ring twice.

The same key with a different body is refused with 409.

When a call can’t start, error.code says why, such as user_already_in_call or calling_allowance_reached. The reference lists every code each calling request can return; Handle errors covers what to do.

If your plan changes

If the workspace moves off Boost, new calls stop with 403 and api_writes_unavailable. A call that’s already connected keeps going, and the token can still follow and end calls it started.