Skip to main content

Phone Numbers

Find and purchase phone numbers, wire inbound calls to your agents, tools, or managers — directly, through a press-a-digit menu, or through a call flow that can also ring people, follow business hours, and take voicemail — set recording, transcripts, and call limits, read call history, decide who answers texts, send and read text messages, and release numbers you no longer need.

All paths on this page are relative to https://api.autessa.com/autessa_poweruser/twilio. Every request is a POST with a JSON body, and every ID is an opaque string. See the Poweruser API overview for authentication and conventions.

The typical flow is two calls: /purchase-number buys a number and returns a configId, then /configure-routing points that number at a resource. Use /search-numbers first if you want to pick the number yourself. A number routes one of three ways:

  • DIRECT — every inbound call goes straight to one resource (directResourceType + directResourceId).
  • PRESS_DIGIT — callers hear a menu and are routed by the digit they press, using routingConfig.digitToResourceMap. These numbers now run as a keypad-menu call flow.
  • FLOW — a call flow decides who answers: AI agents, people, a keypad menu, voicemail, or a mix, with business hours. Set it with /update-call-flow.

Separately, /update-call-settings controls voice and language, recording, transcripts, Call Redaction, call limits, caller-name lookup, blocked callers, AI call behavior, and answering machine detection for every call on the number, and /get-calls reads its call history. /audio-upload-link uploads your own recordings for greetings and menus, and /voice-options lists the voices and languages you can pick.

For texts, /update-text-flow decides who answers them (an AI agent or your team, with business hours, auto-replies, and keyword replies), /sms/threads and /sms/thread read the shared inbox, and /sms/send replies.

A number with nothing set up yet still takes messages: callers go to voicemail, and texts are saved to the shared inbox. See Numbers with nothing set up.

The phone config object​

  • Name
    configId
    Type
    string
    Description

    Unique phone configuration identifier.

  • Name
    phoneNumber
    Type
    string
    Description

    The purchased number in E.164 format (for example +12065550142).

  • Name
    twilioPhoneSid
    Type
    string
    Description

    The carrier's identifier for the number.

  • Name
    routingType
    Type
    string
    Description

    DIRECT, PRESS_DIGIT, or FLOW.

  • Name
    directResourceType
    Type
    string
    Description

    DIRECT routing — the resource kind answering calls: AGENT, TOOL, or MANAGER.

  • Name
    directResourceId
    Type
    string
    Description

    DIRECT routing — the resource answering calls.

  • Name
    directRoutingConfig
    Type
    object
    Description

    DIRECT routing — call settings: environmentVariables, promptTemplateVariables, locallyHostedStt (default true), initialMessage, initialMessagePrompt, conferenceParticipants, clientDisplayMessage.

  • Name
    routingConfig
    Type
    object
    Description

    PRESS_DIGIT routing — digitToResourceMap (map of digit to a routing target with type, id, environmentVariables, promptTemplateVariables) and locallyHostedStt.

  • Name
    callFlow
    Type
    CallFlow | null
    Description

    FLOW routing — the call flow; null otherwise.

  • Name
    callSettings
    Type
    CallSettings
    Description

    The number's call settings. Always present; an empty object means every setting is at its default.

  • Name
    callLogTableId
    Type
    string | null
    Description

    Your company's Phone calls AutessaDB table, or null until the first call creates it. The same table is shared by all your numbers.

  • Name
    textFlow
    Type
    TextFlow | null
    Description

    How texts to the number are handled; see /update-text-flow. null means the default.

  • Name
    textLogTableId
    Type
    string | null
    Description

    Your company's Text messages AutessaDB table, or null until the first text creates it. The same table is shared by all your numbers.

  • Name
    automations
    Type
    object
    Description

    The number's quick automations: textBackMissedCalls (enabled, smsMessage, triggerId, toolId), emailVoicemails (enabled, emails, triggerId, toolId), textForwardSms (enabled, phones, triggerId, toolId), and textForwardEmail (enabled, emails, triggerId, toolId). The ids point at the trigger and tool behind each one, or are null if it was never turned on.

  • Name
    audioPreviewUrls
    Type
    object
    Description

    A map from each uploaded audio file the number uses (an s3:// value from /audio-upload-link) to a short-lived https:// link you can play it from. Audio fields themselves come back exactly as you saved them.

  • Name
    sharingLevel
    Type
    string
    Description

    PRIVATE, SPECIFIC_MEMBER, or COMPANY.

  • Name
    companyPermissionLevel
    Type
    string
    Description

    Access level granted company-wide when shared with the company: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    isActive
    Type
    boolean
    Description

    Whether the number is live. Released numbers become inactive.

  • Name
    createdAt
    Type
    string
    Description

    ISO-8601 creation timestamp.

  • Name
    updatedAt
    Type
    string
    Description

    ISO-8601 timestamp of the last update.

Phone config object (DIRECT)
{
  "configId": "pH9nR3vC6b",
  "phoneNumber": "+12065550142",
  "twilioPhoneSid": "PNa1b2c3d4e5f60718293a4b5c6d7e8f90",
  "routingType": "DIRECT",
  "directResourceType": "AGENT",
  "directResourceId": "V1StGXR8Z5",
  "directRoutingConfig": {
    "environmentVariables": {},
    "promptTemplateVariables": { "companyName": "Acme Corp" },
    "locallyHostedStt": true,
    "initialMessage": "Thanks for calling Acme, how can I help?",
    "initialMessagePrompt": null,
    "conferenceParticipants": [],
    "clientDisplayMessage": null
  },
  "routingConfig": null,
  "callFlow": null,
  "callSettings": {
    "transcript": { "save": true },
    "recording": { "save": true, "announcement": "This call may be recorded." }
  },
  "callLogTableId": "tB7xQ2mL9k",
  "textFlow": null,
  "textLogTableId": "tM3wK8pR5j",
  "automations": {
    "textBackMissedCalls": { "enabled": false, "smsMessage": null, "triggerId": null, "toolId": null },
    "emailVoicemails": { "enabled": true, "emails": ["frontdesk@example.com"], "triggerId": "tR4kP8nW2q", "toolId": "tL6vH3cJ9d" },
    "textForwardSms": { "enabled": false, "phones": [], "triggerId": null, "toolId": null },
    "textForwardEmail": { "enabled": false, "emails": [], "triggerId": null, "toolId": null }
  },
  "sharingLevel": "COMPANY",
  "companyPermissionLevel": "READ",
  "isActive": true,
  "createdAt": "2026-06-01T14:22:05",
  "updatedAt": "2026-06-28T17:42:10"
}

Search available numbers​

POST/twilio/search-numbers

Lists US numbers available to buy. Nothing is reserved — pass the number you pick to /purchase-number as phoneNumber.

Request parameters​

  • Name
    areaCode
    Type
    string
    Description

    Three-digit US area code.

  • Name
    contains
    Type
    string
    Description

    Digits the number should contain, for example "555".

  • Name
    limit
    Type
    integer
    Description

    How many numbers to return, 1–20 (default 10).

Response​

  • Name
    numbers
    Type
    array<object>
    Description

    Available numbers: phoneNumber (E.164), locality, region, and capabilities (sms, voice, mms).

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/search-numbers \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "areaCode": "206", "limit": 5 }'
Response (truncated)
{
  "numbers": [
    {
      "phoneNumber": "+12065550142",
      "locality": "Seattle",
      "region": "WA",
      "capabilities": { "sms": true, "voice": true, "mms": true }
    }
  ],
  "errors": []
}

Purchase a phone number​

POST/twilio/purchase-number

Gets a new US phone number. Numbers are free for calls, and no card is needed. Pick an exact number from /search-numbers, give just an area code, or send {} to let the platform choose. The number takes calls immediately. It starts without routing; configure it with /configure-routing. Texting is off until you turn it on with /sms/attach-number.

Request parameters​

  • Name
    phoneNumber
    Type
    string
    Description

    The exact number to buy, in E.164 format, from /search-numbers.

  • Name
    areaCode
    Type
    string
    Description

    Buy the first available number in this area code.

  • Name
    idempotencyKey
    Type
    string
    Description

    Your own key (up to 64 characters). Retrying with the same key never buys twice.

  • Name
    attachToSms
    Type
    boolean
    Description

    Also turn on texting for the number, exactly as /sms/attach-number does — including its monthly texting fee and card requirement.

Response​

  • Name
    success
    Type
    boolean
    Description

    Whether the purchase succeeded.

  • Name
    configId
    Type
    string
    Description

    The new phone configuration — pass this to every other endpoint on this page.

  • Name
    phoneNumber
    Type
    string
    Description

    The purchased number in E.164 format.

  • Name
    twilioPhoneSid
    Type
    string
    Description

    The carrier's identifier for the number.

  • Name
    message
    Type
    string
    Description

    Human-readable result.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/twilio/purchase-number \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "success": true,
  "configId": "pH9nR3vC6b",
  "phoneNumber": "+12065550142",
  "twilioPhoneSid": "PNa1b2c3d4e5f60718293a4b5c6d7e8f90",
  "message": "Phone number purchased successfully",
  "errors": []
}

Configure routing​

POST/twilio/configure-routing

Sets how inbound calls to a number are handled. For DIRECT routing, supply directResourceType and directResourceId; for PRESS_DIGIT, supply routingConfig with a digitToResourceMap.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to update.

  • Name
    routingType
    Type
    string
    Description

    DIRECT or PRESS_DIGIT.

  • Name
    directResourceType
    Type
    string
    Description

    DIRECT — AGENT, TOOL, or MANAGER.

  • Name
    directResourceId
    Type
    string
    Description

    DIRECT — the resource that answers calls.

  • Name
    routingConfig
    Type
    object
    Description

    PRESS_DIGIT — digitToResourceMap: map of digit ("1", "2", …) to a target { type, id, environmentVariables, promptTemplateVariables }, plus locallyHostedStt.

  • Name
    locallyHostedStt
    Type
    boolean
    Description

    Use Autessa-hosted speech-to-text (default true).

  • Name
    promptTemplateVariables
    Type
    object
    Description

    Values for the resource's @@{variable}@@ prompt template placeholders.

  • Name
    environmentVariables
    Type
    object
    Description

    Environment variables passed to tool executions triggered by the call.

  • Name
    initialMessage
    Type
    string
    Description

    Static greeting spoken when an inbound call connects.

  • Name
    initialMessagePrompt
    Type
    string
    Description

    Prompt sent to the LLM to generate a dynamic greeting when the call connects. Supports @@{variableName}@@ placeholders. Takes the place of initialMessage when provided.

  • Name
    conferenceParticipants
    Type
    array<string>
    Description

    Additional phone numbers dialed into the conference when an inbound call starts; each participant joins on answer.

  • Name
    clientDisplayMessage
    Type
    string
    Description

    Message shown to browser-client conference participants when they receive the call.

Response​

  • Name
    success
    Type
    boolean
    Description

    Whether the routing was applied.

  • Name
    message
    Type
    string
    Description

    Human-readable result.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

curl https://api.autessa.com/autessa_poweruser/twilio/configure-routing \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "routingType": "DIRECT",
    "directResourceType": "AGENT",
    "directResourceId": "V1StGXR8Z5",
    "initialMessage": "Thanks for calling Acme, how can I help?",
    "promptTemplateVariables": { "companyName": "Acme Corp" }
  }'
Response
{
  "success": true,
  "message": "Routing configured successfully",
  "errors": []
}

Update the call flow​

POST/twilio/update-call-flow

Sets who answers the number: AI agents, people, a keypad menu, voicemail, or a mix, optionally with business hours. Setting a flow changes routingType to FLOW. Passing callFlow: null changes it back to DIRECT, and calls go to the number's direct resource again, which is kept while a flow is set. See Who answers for how each destination behaves.

The flow is checked before it's saved. Phone numbers must be in E.164 format, menu keys must be 0–9, *, or #, times must be HH:mm, the time zone must be a valid name such as America/New_York, and you must be able to use every agent and multi-agent it names. A flow that fails a check returns 400 with a plain-language message.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to update.

  • Name
    callFlow
    Type
    CallFlow | null
    Description

    The flow, or null to go back to DIRECT routing.

The call flow object​

  • Name
    greeting
    Type
    string
    Description

    Spoken to every caller first.

  • Name
    greetingAudio
    Type
    string
    Description

    A recording to play instead of greeting: an https:// link, or an audioUri from /audio-upload-link.

  • Name
    businessHours
    Type
    object
    Description

    Optional. timezone (for example America/Los_Angeles), weekly (a list of { day, open, close } with day from MONDAY to SUNDAY and times as HH:mm), closedDates, and closedDestination (a destination for calls outside those hours). Days not listed are closed all day.

    closedDates lists holidays and other days you're closed all day, each as { date, endDate, name } with dates as YYYY-MM-DD. endDate is optional and makes an inclusive range, and name (such as "Thanksgiving") is just a label. A closed date wins over weekly, so every call that day goes to closedDestination.

  • Name
    destination
    Type
    CallDestination
    Description

    Where calls go (during business hours, if set).

The destination object​

  • Name
    type
    Type
    string
    Description

    AI_AGENT, AI_MULTI_AGENT, RING, MENU, VOICEMAIL, or HANG_UP.

  • Name
    message
    Type
    string
    Description

    Spoken before the destination runs, for example "Our office is closed today."

  • Name
    messageAudio
    Type
    string
    Description

    A recording to play instead of message: an https:// link, or an audioUri from /audio-upload-link.

  • Name
    resourceId
    Type
    string
    Description

    AI_AGENT / AI_MULTI_AGENT — the agent or multi-agent that answers. It uses the AI call settings set with /configure-routing.

  • Name
    ring
    Type
    object
    Description

    RING — rings people. See the ring object.

  • Name
    menu
    Type
    object
    Description

    MENU — prompt (the options read to the caller), promptAudio (a recording to play instead), options (a map of key to destination, for example { "1": {...}, "2": {...} }), timeoutSeconds (how long to wait for a key after the prompt, 2 to 30, default 6), invalidMessage (spoken when the caller presses a key that isn't an option), noInputMessage (spoken when they press nothing in time), retries (how many times to repeat the prompt), and noInput (a destination for when the caller never presses a valid key).

  • Name
    voicemail
    Type
    object
    Description

    VOICEMAIL — greeting (played before the beep), greetingAudio (a recording to play instead), maxSeconds (longest message, default 120), finishOnKey (the key that ends the message, default #; "" for none), silenceSeconds (seconds of silence that end the message, 1 to 30, default 5), and transcribe (default true).

The ring object​

  • Name
    targets
    Type
    array<object>
    Description

    Who to ring. Each target is { to, label, ringSeconds }: to is a phone number in E.164 format or client:<identity> for a teammate's browser phone, label is an optional name such as "Front desk", and ringSeconds overrides the ring time for that target.

  • Name
    strategy
    Type
    string
    Description

    SIMULTANEOUS rings everyone at once and the first to answer gets the call; SEQUENTIAL rings one at a time, in order.

  • Name
    ringSeconds
    Type
    integer
    Description

    How long each target rings when it has no ringSeconds of its own (default 20).

  • Name
    requireKeyPress
    Type
    boolean
    Description

    The person who answers must press 1 to accept the call (default false). Turn it on for cell phones, so a personal voicemail that picks up can't take the caller; the call moves on as if nobody answered.

  • Name
    whisper
    Type
    string
    Description

    Spoken only to the person who answers, before they're connected, for example "Call from the sales line."

  • Name
    callerId
    Type
    string
    Description

    What the rung phone shows: BUSINESS_NUMBER (default) or CALLER. If the carrier won't show the caller's number, the business number is shown.

  • Name
    waitAudio
    Type
    string
    Description

    Played on a loop to the caller while phones ring, instead of a ringing tone: an https:// link, or an audioUri from /audio-upload-link.

  • Name
    maxTotalSeconds
    Type
    integer
    Description

    SEQUENTIAL only. Stop ringing after this many seconds in total, even if some targets haven't rung yet.

  • Name
    noAnswer
    Type
    CallDestination
    Description

    Where the call goes when nobody answers. If it's not set, the caller goes to voicemail.

Response​

The updated phone config object.

curl https://api.autessa.com/autessa_poweruser/twilio/update-call-flow \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "callFlow": {
      "greeting": "Thanks for calling Acme.",
      "businessHours": {
        "timezone": "America/New_York",
        "weekly": [
          { "day": "MONDAY", "open": "09:00", "close": "17:00" },
          { "day": "FRIDAY", "open": "09:00", "close": "15:00" }
        ],
        "closedDates": [
          { "date": "2026-11-26", "endDate": "2026-11-27", "name": "Thanksgiving" }
        ],
        "closedDestination": { "type": "AI_AGENT", "resourceId": "V1StGXR8Z5" }
      },
      "destination": {
        "type": "MENU",
        "menu": {
          "prompt": "Press 1 for sales or 2 for support.",
          "timeoutSeconds": 8,
          "invalidMessage": "Sorry, that is not an option.",
          "retries": 2,
          "options": {
            "1": {
              "type": "RING",
              "ring": {
                "targets": [
                  { "to": "+14155550100", "label": "Sales desk" },
                  { "to": "+14155550101", "label": "Sam cell", "ringSeconds": 25 }
                ],
                "strategy": "SIMULTANEOUS",
                "ringSeconds": 20,
                "requireKeyPress": true,
                "whisper": "Call from the sales line.",
                "noAnswer": { "type": "VOICEMAIL" }
              }
            },
            "2": { "type": "AI_AGENT", "resourceId": "kZ3mQ9pW2x" }
          },
          "noInput": { "type": "VOICEMAIL" }
        }
      }
    }
  }'

Update call settings​

POST/twilio/update-call-settings

Sets the number's voice and language, recording, transcripts, Call Redaction, call limits, caller-name lookup, blocked callers, AI call behavior, and answering machine detection. The settings apply to every call on it, incoming and outgoing, whether an agent or a person handles it. A call already in progress keeps the settings it started with. Calls placed with the Make Phone Call tool can override them for one call.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to update.

  • Name
    callSettings
    Type
    CallSettings
    Description

    The new settings. Sections you leave out use their defaults.

The call settings object​

  • Name
    speech
    Type
    object
    Description

    The voice and language for everything the number says (greetings, messages, menus, voicemail greetings, the recording disclosure, the silence prompt, and transfer announcements). voiceModel and voiceName pick a voice, in the same shape as an agent's voice; leave them out to use the answering agent's voice, or a standard voice when no agent is involved. language is a language code such as en-US or es-US; on AI calls it also sets the language speech recognition listens for. See /voice-options for the values you can use.

  • Name
    transcript
    Type
    object
    Description

    save — keep a transcript of each call (default true). retentionDays — delete each call's transcript and voicemail transcript this many days after the call; leave it out to keep them.

  • Name
    recording
    Type
    object
    Description

    save — keep each call's audio (default false). announcement — the disclosure played before the call connects when recording; defaults to "This call may be recorded." and "" plays nothing. retentionDays — delete each call's recording and voicemail recording this many days after the call; leave it out to keep them. Recording laws vary, and you're responsible for getting any consent they require.

  • Name
    redaction
    Type
    object
    Description

    Call Redaction, which removes personal info from recordings and transcripts before they're saved. Billed at $0.01 per call. enabled (default false); redact — what to remove, any of CARD_NUMBER, CARD_EXPIRY, CARD_CVV, SSN, BANK_ACCOUNT, ACCOUNT_NUMBER, DATE_OF_BIRTH, PHONE, EMAIL, ADDRESS (default: all); audioRedaction — replace removed audio with SILENCE or TONE. It doesn't change the agent's conversation history, which still contains what was said live.

  • Name
    limits
    Type
    object
    Description

    maxDurationMinutes — end calls after this long; maxDurationWarning — spoken before that limit; maxDurationWarningSeconds — how long before the limit the warning plays (10 to 300, default 30); silenceTimeoutSeconds — end the call after this much silence; silencePrompt — asked before hanging up on silence (default "Are you still there?"); silencePromptRepeats — how many times it's asked before the call ends (0 to 3, default 1; 0 hangs up without asking).

  • Name
    callerInfo
    Type
    object
    Description

    lookupCallerName — look up incoming callers' names from carrier caller-ID records. The carrier charges a small fee per lookup, included in the call's price.

  • Name
    screening
    Type
    object
    Description

    Blocks unwanted incoming calls. blockedNumbers — phone numbers in E.164 format that can't reach this number; rejectAnonymous — also block callers who hide their number (default false); blockedMessage — spoken to blocked callers before hanging up. Leave blockedMessage out and blocked calls get a busy signal without being answered.

  • Name
    ai
    Type
    object
    Description

    How AI agents handle the conversation. interruptions — whether the caller can talk over the agent (default true); interruptionSensitivity — LOW, MEDIUM (default), or HIGH, how easily the caller's voice interrupts; endOfTurn — FAST, NORMAL (default), or PATIENT, how long the agent waits after the caller stops talking; hangUpPhrases — a list of phrases, and when the agent's reply contains one, the call ends after the reply plays.

  • Name
    answeringMachine
    Type
    object
    Description

    Outgoing calls. detection — OFF, ON (tell people and answering machines apart), or WAIT_FOR_BEEP (also wait for the machine's beep before leaving a voicemail message); timeoutSeconds — how long to listen before deciding (2 to 60). Leave the section out and detection turns on by itself for calls that leave a voicemail message or generate their opening line.

  • Name
    callLogTableId
    Type
    string
    Description

    Read-only. Your company's Phone calls table; ignored if sent.

Response​

The updated phone config object.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/update-call-settings \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "callSettings": {
      "speech": { "language": "en-US" },
      "transcript": { "save": true, "retentionDays": 365 },
      "recording": { "save": true, "announcement": "This call may be recorded for quality.", "retentionDays": 90 },
      "redaction": {
        "enabled": true,
        "redact": ["CARD_NUMBER", "CARD_EXPIRY", "CARD_CVV", "SSN"],
        "audioRedaction": "TONE"
      },
      "limits": {
        "maxDurationMinutes": 30,
        "maxDurationWarning": "We need to wrap up in a minute.",
        "maxDurationWarningSeconds": 60,
        "silenceTimeoutSeconds": 20,
        "silencePromptRepeats": 2
      },
      "callerInfo": { "lookupCallerName": true },
      "screening": { "blockedNumbers": ["+15555550123"], "rejectAnonymous": true },
      "ai": {
        "interruptionSensitivity": "LOW",
        "endOfTurn": "PATIENT",
        "hangUpPhrases": ["Have a great day"]
      }
    }
  }'

Update the text flow​

POST/twilio/update-text-flow

Sets how texts to the number are handled: by an AI agent or with no AI, optionally with business hours, auto-replies, and keyword replies. Texts follow this setting whatever the number's call routing is. See Texts for what each setting does.

Passing textFlow: null goes back to the default: if the number sends calls straight to one AI agent, that agent answers texts; otherwise texts get no reply and are saved to the shared inbox and the Text messages table.

STOP, START, and HELP are always handled first for compliance, before keyword replies or anything else, and can't be changed here.

The flow is checked before it's saved, the same way as a call flow: times must be HH:mm, the time zone must be a valid name, and you must be able to use any agent it names. A flow that fails a check returns 400 with a plain-language message.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to update.

  • Name
    textFlow
    Type
    TextFlow | null
    Description

    The text flow, or null for the default.

The text flow object​

  • Name
    keywordReplies
    Type
    array<object>
    Description

    Fixed replies to specific words, each { keyword, reply }. A text matches when the whole message equals keyword, ignoring capital letters and spaces around it. Checked before open or closed, at any hour and whoever answers. A matching text gets reply and goes no further.

  • Name
    businessHours
    Type
    object | null
    Description

    Hours just for texts: timezone, weekly, and optional closedDates, in the same shape as a call flow's businessHours, without closedDestination (use closed instead). Leave out for no hours.

  • Name
    useCallFlowHours
    Type
    boolean
    Description

    true uses the business hours of the number's call flow instead of businessHours, so the two always match.

  • Name
    open
    Type
    TextHandling
    Description

    How texts are handled during business hours, or at all times when there are no hours.

  • Name
    closed
    Type
    TextHandling
    Description

    How texts are handled outside business hours. Leave out to handle them the same as open.

The text handling object​

  • Name
    type
    Type
    string
    Description

    AI_AGENT (an agent answers) or NO_AI (texts wait in the shared inbox for your team).

  • Name
    resourceId
    Type
    string
    Description

    AI_AGENT — the agent that answers. Leave out to use the agent the number sends calls to directly.

  • Name
    autoReply
    Type
    object
    Description

    NO_AI only — an automatic reply: message (the text to send) and onceEveryHours (send it to the same person at most once in this many hours; default 24, 0 replies to every text, at most 720).

Response​

  • Name
    config
    Type
    object
    Description

    The updated phone config object, with the new textFlow.

  • Name
    permission
    Type
    string
    Description

    Your permission level on the number.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/update-text-flow \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "textFlow": {
      "keywordReplies": [
        { "keyword": "HOURS", "reply": "We are open Monday to Friday, 9 to 5." }
      ],
      "useCallFlowHours": true,
      "open": {
        "type": "NO_AI",
        "autoReply": {
          "message": "Thanks for your message. We will text you back shortly.",
          "onceEveryHours": 24
        }
      },
      "closed": { "type": "AI_AGENT", "resourceId": "V1StGXR8Z5" }
    }
  }'

List calls​

POST/twilio/get-calls

Returns the number's calls, newest first, from your company's Phone calls table. Incoming and outgoing calls are both included, with or without AI.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration whose calls to list.

  • Name
    limit
    Type
    integer
    Description

    Calls per page, up to 50 (default 10).

  • Name
    after
    Type
    string
    Description

    The next value from the previous page.

Response​

  • Name
    tableId
    Type
    string | null
    Description

    The Phone calls AutessaDB table, or null if no call has been logged yet. You can query it with the AutessaDB API.

  • Name
    calls
    Type
    array<object>
    Description

    The calls on this page. Each has rowId (its row in the table), callId, direction (INBOUND or OUTBOUND), businessNumber, otherNumber, callerName, callerLocation, forwardedFrom, handledBy, conversationId (the agent conversation, for AI calls), startedAt and endedAt (UTC, ISO-8601), durationSeconds, status, answeredBy, endedBy, transferredTo, keypadResponse, transcript, recordingUrl, voicemailRecordingUrl, voicemailTranscript, redactionStatus, and processingError. The recording links are valid for 10 minutes. See the guide for the values of each column.

  • Name
    next
    Type
    string | null
    Description

    Pass as after to get the next page; null on the last page.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/get-calls \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b", "limit": 1 }'
Response
{
  "tableId": "tB7xQ2mL9k",
  "calls": [
    {
      "rowId": "r8KdW2pQ5n",
      "callId": "c3Vt9LmX2a",
      "direction": "INBOUND",
      "businessNumber": "+12065550142",
      "otherNumber": "+14155550100",
      "callerName": "JANE DOE",
      "callerLocation": "San Francisco, CA, US",
      "forwardedFrom": null,
      "handledBy": "Front desk agent",
      "conversationId": "cv5Hn7Rt2w",
      "startedAt": "2026-10-09T17:02:11Z",
      "endedAt": "2026-10-09T17:05:48Z",
      "durationSeconds": 217,
      "status": "COMPLETED",
      "answeredBy": "HUMAN",
      "endedBy": "AGENT",
      "transferredTo": null,
      "keypadResponse": null,
      "transcript": "Agent: Thanks for calling Acme, how can I help?\nCaller: I'd like to move my appointment...",
      "recordingUrl": "https://...",
      "voicemailRecordingUrl": null,
      "voicemailTranscript": null,
      "redactionStatus": "DONE",
      "processingError": null
    }
  ],
  "next": "eyJzIjoiMjAyNi0xMC0wOVQxNzowMjoxMVoifQ"
}

Set an automation​

POST/twilio/set-automation

Turns one of the number's quick automations on or off. Each automation is a regular trigger on the Phone calls table (or, for forwarding texts, the Text messages table) that runs a regular tool, so you can see and edit it like any other. Turning one off disables its trigger without deleting it, and turning it back on reuses it.

  • TEXT_BACK_MISSED_CALLS — texts the caller from this number when an incoming call isn't answered, is busy, or goes to voicemail. The number must be able to text.
  • EMAIL_VOICEMAILS — emails the voicemail transcript and a link to the call when a caller leaves a voicemail.
  • FORWARD_TEXTS_SMS — texts every incoming text on to up to 5 phones, as "From +14155550100: " followed by the message. The forwarded texts are sent from this number, so it must be able to text and the phones must be allowed to receive texts from it (texting the number once from each phone is enough). Texts from those phones are never forwarded.
  • FORWARD_TEXTS_EMAIL — emails every incoming text to up to 5 people.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration.

  • Name
    automation
    Type
    string
    Description

    TEXT_BACK_MISSED_CALLS, EMAIL_VOICEMAILS, FORWARD_TEXTS_SMS, or FORWARD_TEXTS_EMAIL.

  • Name
    enabled
    Type
    boolean
    Description

    Turn the automation on or off.

  • Name
    smsMessage
    Type
    string
    Description

    TEXT_BACK_MISSED_CALLS — the text to send.

  • Name
    emails
    Type
    array<string>
    Description

    EMAIL_VOICEMAILS and FORWARD_TEXTS_EMAIL — who gets the email, up to 5 addresses.

  • Name
    phones
    Type
    array<string>
    Description

    FORWARD_TEXTS_SMS — the phones to forward texts to, up to 5, in E.164 format.

Response​

The updated phone config object, with the automation's state in automations.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/set-automation \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "automation": "TEXT_BACK_MISSED_CALLS",
    "enabled": true,
    "smsMessage": "Sorry we missed your call. We will call you back shortly."
  }'
POST/twilio/audio-upload-link

Uploads your own recording, such as a greeting, menu prompt, voicemail greeting, or hold music, for use in a number's call flow. It takes three steps:

  1. Get a link. Call this endpoint with the number and the file type. The response has an uploadUrl, an audioUri, and a contentType.
  2. Upload the file. Send the audio file's bytes with an HTTP PUT to uploadUrl, with a Content-Type header set to exactly the contentType from step 1. Any other content type is refused. Upload before expiresInSeconds runs out, or get a new link.
  3. Use it. Save audioUri into an audio field with /update-call-flow: greetingAudio, messageAudio, a menu's promptAudio, a voicemail's greetingAudio, or a ring's waitAudio. Audio fields also accept your own https:// links, so this step-by-step upload is only needed for files you don't host.

When an audio field is set, it plays instead of the matching text. The phone config object returns a playable link for each uploaded file in audioPreviewUrls.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration the recording is for.

  • Name
    fileType
    Type
    string
    Description

    mp3 or wav.

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Where to PUT the file. It expires after expiresInSeconds.

  • Name
    audioUri
    Type
    string
    Description

    The value to save in an audio field once the upload is done.

  • Name
    contentType
    Type
    string
    Description

    The Content-Type header to send with the upload, for example audio/mpeg.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    How long uploadUrl stays valid.

1. Get a link
curl https://api.autessa.com/autessa_poweruser/twilio/audio-upload-link \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b", "fileType": "mp3" }'
Response
{
  "uploadUrl": "https://...",
  "audioUri": "s3://.../greeting.mp3",
  "contentType": "audio/mpeg",
  "expiresInSeconds": 900
}
2. Upload the file
curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: audio/mpeg" \
  --data-binary @greeting.mp3
3. Use it as the greeting
curl https://api.autessa.com/autessa_poweruser/twilio/update-call-flow \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "callFlow": {
      "greeting": "Thanks for calling Acme.",
      "greetingAudio": "s3://.../greeting.mp3",
      "destination": { "type": "AI_AGENT", "resourceId": "V1StGXR8Z5" }
    }
  }'

List voice options​

POST/twilio/voice-options

Lists the languages and voices you can use in a number's speech call settings. It takes no parameters; send an empty JSON object.

Response​

  • Name
    languages
    Type
    array<object>
    Description

    The supported languages, each with code (the value for speech.language, such as en-US) and label (a readable name such as "English (US)").

  • Name
    voices
    Type
    array<object>
    Description

    The voices you can pick, the same list agents offer, including your company's custom voices. Use a voice's model and name as speech.voiceModel and speech.voiceName.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/voice-options \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List all phone configs​

POST/twilio/get-all-configs

Lists every phone configuration visible to the linked user.

Request parameters​

None — send an empty object {}.

Response​

  • Name
    configs
    Type
    array<PhoneConfig>
    Description

    The phone configurations, each in the phone config object shape.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/get-all-configs \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "configs": [
    {
      "configId": "pH9nR3vC6b",
      "phoneNumber": "+12065550142",
      "routingType": "DIRECT",
      "directResourceType": "AGENT",
      "directResourceId": "V1StGXR8Z5",
      "sharingLevel": "COMPANY",
      "isActive": true,
      "createdAt": "2026-06-01T14:22:05"
    }
  ],
  "errors": []
}

Get a phone config​

POST/twilio/get-config

Retrieves one phone configuration, including its full routing details and the calling user's access level.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to fetch.

Response​

  • Name
    config
    Type
    PhoneConfig
    Description

    The phone config object.

  • Name
    permission
    Type
    string
    Description

    The calling user's access level on this config: READ, WRITE, PUBLISH, or ADMIN.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/get-config \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b" }'
Response (truncated)
{
  "config": {
    "configId": "pH9nR3vC6b",
    "phoneNumber": "+12065550142",
    "routingType": "DIRECT",
    "directResourceType": "AGENT",
    "directResourceId": "V1StGXR8Z5",
    "isActive": true
  },
  "permission": "ADMIN",
  "errors": []
}

Release a phone number​

POST/twilio/release-number

Releases the number back to the carrier and deactivates the configuration. Inbound calls to the number stop working immediately, and the number cannot be recovered — buy a new one with /purchase-number if needed. Any monthly texting fee stops from the next month. A hosted number stops being hosted. A number linked from your own Twilio account is only unlinked — it stays in your Twilio account.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration whose number to release.

Response​

  • Name
    success
    Type
    boolean
    Description

    Whether the release succeeded.

  • Name
    message
    Type
    string
    Description

    Human-readable result.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/release-number \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b" }'
Response
{
  "success": true,
  "message": "Phone number released successfully",
  "errors": []
}

Turn on texting for a number​

POST/twilio/sms/attach-number

Turns on texting for a number by adding it to your company's Text Messaging registration. This starts the number's monthly texting fee, charged to your company's card on file — a card is required, and the call fails with PAYMENT_METHOD_REQUIRED without one. The number texts, and is billed, once the registration is approved; if it already is, that happens right away. The fee amount is shown on the number's page in the web app.

Use /sms/detach-number to turn texting off.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to turn texting on for.

Response​

  • Name
    success
    Type
    boolean
    Description

    Whether texting was turned on.

  • Name
    message
    Type
    string
    Description

    Human-readable result.

  • Name
    config
    Type
    PhoneConfig
    Description

    The number after the change, with its updated texting status.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/attach-number \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b" }'

Turn off texting for a number​

POST/twilio/sms/detach-number

Turns texting off for a number. The number keeps working for calls, and its monthly texting fee stops from the next month.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to turn texting off for.

Response​

Same shape as /sms/attach-number.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/detach-number \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b" }'

Send a text message​

POST/twilio/sms/send

Sends one text from a company number to a US number. The message reaches a real person, so it's checked first: your company needs a finished Text Messaging registration (or the number comes from your own connected Twilio account), and the recipient needs an approved consent record or a text to you within the last year. People who replied STOP are never texted. Requires write access to the phone configuration.

A refused text still returns 200: success is false, errorCode says why, and errorMessage explains it in plain language. The codes are the same as the Send SMS tool's.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration to text from.

  • Name
    to
    Type
    string
    Description

    The recipient's US number; (415) 555-0100 and +14155550100 are both accepted.

  • Name
    body
    Type
    string
    Description

    The message text, at most 1600 characters.

Response​

  • Name
    success
    Type
    boolean
    Description

    Whether the carrier accepted the text.

  • Name
    messageId
    Type
    string
    Description

    Autessa's ID for the logged message.

  • Name
    twilioMessageSid
    Type
    string
    Description

    The carrier's identifier for the message.

  • Name
    status
    Type
    string
    Description

    QUEUED, ACCEPTED, SENDING, or SENT when accepted; BLOCKED or FAILED when not sent. Delivery shows later in /sms/messages.

  • Name
    from
    Type
    string
    Description

    The sending number in E.164 format.

  • Name
    to
    Type
    string
    Description

    The recipient in E.164 format.

  • Name
    segments
    Type
    integer
    Description

    How many SMS segments the message used, when known.

  • Name
    errorCode
    Type
    string
    Description

    Why the text wasn't sent — only when success is false.

  • Name
    errorMessage
    Type
    string
    Description

    Plain-language explanation of errorCode.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/send \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": "pH9nR3vC6b",
    "to": "+14155550100",
    "body": "Hi Sam, your order has shipped. Reply STOP to opt out."
  }'
Response
{
  "success": true,
  "messageId": "mS4kT8wQ2n",
  "twilioMessageSid": "SMa1b2c3d4e5f60718293a4b5c6d7e8f90",
  "status": "QUEUED",
  "from": "+12065550142",
  "to": "+14155550100",
  "segments": 1,
  "errors": []
}
Response (refused)
{
  "success": false,
  "errorCode": "CONSENT_REQUIRED",
  "errorMessage": "This person hasn't agreed to receive texts from you. Add a consent record for them in SMS Consent, or wait for them to text you first.",
  "errors": []
}

List text messages​

POST/twilio/sms/messages

Lists a number's text messages, newest first — incoming texts, replies, and sends that were refused, with the reason. The other party's number is masked. Company owners can omit configId to list every company number.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration whose messages to list.

  • Name
    pageSize
    Type
    integer
    Description

    Messages per page (default 25, at most 100).

  • Name
    cursor
    Type
    string
    Description

    The previous page's nextCursor; omit for the first page.

Response​

  • Name
    messages
    Type
    array<object>
    Description

    The page of messages: messageId, configId, direction (INBOUND or OUTBOUND), origin, status, ourNumber, counterparty (masked), body, segments, errorCode, errorMessage, twilioMessageSid, createdAt, and statusUpdatedAt.

  • Name
    nextCursor
    Type
    string
    Description

    Pass as cursor to get the next page; absent on the last page.

  • Name
    errors
    Type
    array<string>
    Description

    Error messages, if any occurred.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/messages \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b", "pageSize": 25 }'
Response (truncated)
{
  "messages": [
    {
      "messageId": "mS4kT8wQ2n",
      "configId": "pH9nR3vC6b",
      "direction": "OUTBOUND",
      "origin": "SDK",
      "status": "DELIVERED",
      "ourNumber": "+12065550142",
      "counterparty": "+1415•••0100",
      "body": "Hi Sam, your order has shipped. Reply STOP to opt out.",
      "segments": 1,
      "createdAt": "2026-09-22T17:42:10Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjI1fQ",
  "errors": []
}

List text threads​

POST/twilio/sms/threads

Lists the number's shared inbox: one thread per person who has texted the number or been texted from it, with the most recent activity first. Read a thread's messages with /sms/thread, and reply with /sms/send.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration whose inbox to list.

  • Name
    limit
    Type
    integer
    Description

    Threads per page, up to 50 (default 20).

  • Name
    after
    Type
    string
    Description

    The next value from the previous page.

Response​

  • Name
    threads
    Type
    array<object>
    Description

    The threads on this page. Each has otherNumber (the person's number in E.164 format), lastBody and lastDirection (INBOUND or OUTBOUND) of the latest text, lastAt (UTC, ISO-8601), and messageCount.

  • Name
    next
    Type
    string | null
    Description

    Pass as after to get the next page; null on the last page.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/threads \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b", "limit": 20 }'
Response
{
  "threads": [
    {
      "otherNumber": "+14155550100",
      "lastBody": "Is the shop open Saturday?",
      "lastDirection": "INBOUND",
      "lastAt": "2026-10-09T17:02:11Z",
      "messageCount": 4
    }
  ],
  "next": null
}

Get a text thread​

POST/twilio/sms/thread

Returns the texts between the number and one person, newest first.

Request parameters​

  • Name
    configId
    Type
    string
    Description

    The phone configuration.

  • Name
    otherNumber
    Type
    string
    Description

    The person's number, as returned in otherNumber by /sms/threads.

  • Name
    limit
    Type
    integer
    Description

    Messages per page, up to 200 (default 50).

  • Name
    before
    Type
    string
    Description

    The next value from the previous page, to load older messages.

Response​

  • Name
    messages
    Type
    array<object>
    Description

    The messages on this page. Each has id, direction (INBOUND or OUTBOUND), body, sentAt (UTC, ISO-8601), status, and handledBy (the agent's name, Auto-reply, Keyword reply, Staff: and the teammate's name, or Automation).

  • Name
    next
    Type
    string | null
    Description

    Pass as before to get older messages; null when there are none.

To reply, use /sms/send with the same configId and otherNumber as to. The reply is sent as the business number and shows up in the thread with handledBy set to Staff: and your name. It's checked like any other text: the number must be able to text, and the person must not have opted out and must have texted you within the last year or have an approved consent record.

cURL
curl https://api.autessa.com/autessa_poweruser/twilio/sms/thread \
  -X POST \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "configId": "pH9nR3vC6b", "otherNumber": "+14155550100", "limit": 2 }'
Response
{
  "messages": [
    {
      "id": "mT7rQ2kW9p",
      "direction": "OUTBOUND",
      "body": "Yes, 10 to 2 on Saturdays.",
      "sentAt": "2026-10-09T17:05:40Z",
      "status": "DELIVERED",
      "handledBy": "Staff: Dana Lee"
    },
    {
      "id": "mS4kT8wQ2n",
      "direction": "INBOUND",
      "body": "Is the shop open Saturday?",
      "sentAt": "2026-10-09T17:02:11Z",
      "status": "RECEIVED",
      "handledBy": null
    }
  ],
  "next": "eyJiIjoiMjAyNi0xMC0wOVQxNzowMjoxMVoifQ"
}

Errors​

StatusWhen
200Success — check success and errors for operation-level failures (no numbers available, invalid routing target, a refused text).
400A call flow, text flow, call settings, or automation request failed a check (for example a phone number not in E.164 format, or an agent you can't use). The message says what to fix.
401Invalid or missing poweruser key, or the linked user lacks access to the config.
403Scoped key without the endpoint in its allow-list.
408Server-side error; errors contains the message.