Voice and dialer

Human and AI campaigns

A dialer campaign runs on a phone account you connected to SwooshConnect. Its mode decides who dials.

Create or change a campaign with dialer_save_campaign and list them with dialer_campaigns. List the caller ids you can use with calls_numbers. A field you leave out keeps its saved value. No tool places a call.

Importing contacts

dialer_import_contacts takes either CSV text or a JSON rows array, never both. CSV accepts up to 20,000 rows, counting invalid ones; JSON rows accept up to 5,000.

name,phone,timezone,ai_consent,consent_source,consent_text,consent_at
Dana Levi,+15551234567,America/New_York,written,web form 2026-09-01,I agree to automated calls,2026-09-01

Column names are name, phone (or number, mobile), timezone (or tz), ai_consent, consent_source, consent_text and consent_at. In JSON rows the same fields are name, phone, timezone, aiConsent, consentSource, consentText and consentAt.

• ai_consent is none, express or written. Empty means none.
• A row that claims express or written consent needs a consent_source, and consent_at, when given, must be an ISO date (for example 2026-09-01) or an ISO date-time with an offset, and must not be in the future. Any other format drops that row's consent: it is imported with no consent and counted in consentRejected.
• Numbers already on the do-not-call list, numbers already in the campaign (duplicates) and invalid numbers are skipped and counted. A number repeated inside the same CSV is counted as invalid, not as a duplicate.
• The result reports added, duplicates, dnc, invalid and consentRejected. Check consentRejected after every import.
• To record or fix consent on an existing contact, use dialer_set_consent with where the consent came from.

Consent levels

• none: the AI never calls this contact.
• express: enough for a non-marketing AI campaign.
• written: required when the campaign is marked marketing. An express contact is never called by a marketing campaign.
• Every consent must have a source you can show: where and when the person agreed.

Calling hours

The AI calls a contact only when it is between 08:00 and 21:00 in the contact's own time zone and also inside the campaign's own hours. Both windows must still be open 2 minutes from now, so no call starts as a window closes.

Do not call and opt-out

• A number on the do-not-call list is never dialed by any campaign. Add one with dialer_add_dnc.
• Every AI call opens by saying it is an automated assistant, names the business and a callback number, and tells the person they can say stop or press 9 at any time.
• An opt-out phrase such as stop, unsubscribe or do not call always wins, even if the person also said yes. The assistant's opt_out tool adds the number to do-not-call and ends the conversation.

Daily cap, pacing and call length

• An AI campaign must have maxCallsPerDay from 1 to 500. One without a cap is never dialed. The cap counts calls as they are placed.
• One AI call at a time per campaign.
• An AI call ends after 9 minutes.
• If the call reaches voicemail or an answering machine, the call is logged and ended. The AI never leaves a voicemail.
• Recording is off on every assistant.

The receptionist

The receptionist answers inbound calls to a number on your connected phone account. Read it with voice_settings_get and change it with voice_settings_save.

• It asks the caller whether they would like to be connected to a person. Its request_transfer tool records the answer first, and transfers only after a clear yes.
• An opt-out phrase blocks the transfer even after an earlier yes.
• Outside your business hours it takes a message instead of transferring (the after_hours result).
• With no transfer number or nobody available, it continues helping and does not transfer.
• It can look up a caller's first name from your contacts (lookup_caller) to greet them.
• Enabling it routes the chosen number to the receptionist. Disabling it routes the number back to where it rang before; routingWarning tells you if a number could not be routed back.

Reading call results

calls_log lists calls the assistant handled: inbound calls it answered and outbound AI campaign calls, with the outcome, consent, transfer, opt-out and summary. There are no webhooks, so poll.

• Start with since set to the current ISO time, and pass back nextCursor on each poll.
• A call appears exactly once, only after it has ended and been over for about 5 minutes, so its outcome is final.
• A null nextCursor means nothing new arrived: keep your previous cursor.
• Without since you get a newest-first snapshot that may repeat calls and includes calls in progress. A summary can arrive a few minutes after the call ends.

You pay for what you connect. Nothing else.