--- title: "Voice and dialer" summary: "How SwooshConnect handles calls on your connected phone account: human and AI dialer campaigns, consent, calling hours, the receptionist, and polling call results." updated: "2026-09-30" status: beta origin: official url: "https://swooshconnect.com/docs/voice/" --- # Voice and dialer How SwooshConnect handles calls on your connected phone account: human and AI dialer campaigns, consent, calling hours, the receptionist, and polling call results. ## For AI agents - NEVER mark a contact's consent (`dialer_set_consent`, or ai_consent / aiConsent on import) unless the person really gave it and you can name the real source. Consent with no source is rejected. - NEVER import or treat a contact as callable without a time zone. A contact with no time zone is never called by the AI. - A campaign with mode human is dialed only by a person on the dialer screen. NEVER try to make it run automatically. - No tool places a call. `dialer_save_campaign` and `dialer_import_contacts` only prepare a campaign; the AI caller or a person dials. - An AI campaign needs maxCallsPerDay (1 to 500), a business name and a reason for the call. NEVER raise the cap to work around a block. - A marketing AI campaign needs written consent. Express consent is not enough. NEVER downgrade this. - NEVER re-add a contact who said stop. Use `dialer_add_dnc` when someone opts out. - To read results, poll `calls_log` with `since` and keep `nextCursor`. There are no webhooks. - This page is general guidance, not legal advice. Tell the user to check their own telemarketing rules. ## Human and AI campaigns A dialer campaign runs on a phone account you connected to SwooshConnect. Its mode decides who dials. | Mode | Who dials | Consent needed | | --- | --- | --- | | human (default) | A person, on the dialer screen in https://swooshrank.com/portal/connect | No automated-call consent | | ai | The automated caller, only to contacts with recorded consent, inside calling hours, under the daily cap | express, or written for a marketing campaign | 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. ```text 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. > **Never:** A contact with no time zone is never called by the AI. There is no default zone. ## 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. > **Note:** General guidance, not legal advice. Rules on automated and marketing calls depend on your country, state and use case. Check them before you run a campaign.