autessa.twilio
Twilio voice and SMS connector operations.
Texting from a script
Scripts can find numbers to buy, send texts, and read a number's text history. Sending is checked exactly like the Send SMS tool: 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. Opted-out numbers are never texted.
const { ok, data } = autessa.twilio.sendSms({
configId: 'pH9nR3vC6b',
to: '+14155550100',
body: 'Hi Sam, your order has shipped. Reply STOP to opt out.'
});
if (data.success) console.log('sent', data.messageId, data.status, data.segments);
else console.log('not sent', data.errorCode, data.errorMessage);
A refused text isn't an exception: success is false, errorCode says why, and errorMessage explains it in plain language.
let cursor;
do {
const { ok, data } = autessa.twilio.listSmsMessages({ configId: 'pH9nR3vC6b', pageSize: 25, cursor });
if (!ok) break;
data.messages.forEach(m => console.log(m.direction, m.counterparty, m.status, m.body));
cursor = data.nextCursor;
} while (cursor);
Messages come newest first, with the other party's number masked. Blocked sends are included with their reason.
const { ok, data } = autessa.twilio.searchNumbers({ areaCode: '206', limit: 10 });
data.numbers.forEach(n => console.log(n.phoneNumber, n.locality, n.region));
sendSms, listSmsMessages, and searchNumbers ship with the Text Messaging release. The reference below is generated from the platform and lists them once the release is live.
Calls from a script
Scripts can set who answers a number, change its recording and call-limit settings, read its call history, and turn its quick automations on or off. What each setting does is explained in the Phone Numbers guide.
const { ok, data } = autessa.twilio.updateCallFlow({
configId: 'pH9nR3vC6b',
callFlow: {
greeting: 'Thanks for calling Acme Dental.',
destination: {
type: 'RING',
ring: {
targets: [
{ to: '+14155550100', label: 'Front desk' },
{ to: '+14155550101', label: 'Office manager', ringSeconds: 30 }
],
strategy: 'SEQUENTIAL',
ringSeconds: 20,
maxTotalSeconds: 45,
requireKeyPress: true,
whisper: 'Call from the Acme Dental line.',
noAnswer: { type: 'VOICEMAIL', voicemail: { maxSeconds: 120, finishOnKey: '#', transcribe: true } }
}
}
}
});
if (ok) console.log(data.routingType); // "FLOW"
Pass callFlow: null to go back to sending every call straight to the number's agent or multi-agent. An invalid flow (an unknown agent, a bad time, a phone number not in E.164 format) comes back with ok false and a plain-language message. Every flow field, including holiday closedDates, menu timing and messages, and ring options like callerId and waitAudio, is described in the call flow object reference.
// 1. get an upload link
const link = autessa.twilio.audioUploadLink({ configId: 'pH9nR3vC6b', fileType: 'mp3' }).data;
console.log(link.uploadUrl, link.contentType, link.audioUri);
// 2. PUT the file to link.uploadUrl with the header "Content-Type: <link.contentType>",
// from curl or any HTTP client that can send a file's raw bytes
// 3. once it's uploaded, save link.audioUri into an audio field
autessa.twilio.updateCallFlow({
configId: 'pH9nR3vC6b',
callFlow: {
greeting: 'Thanks for calling Acme Dental.',
greetingAudio: link.audioUri,
destination: { type: 'AI_AGENT', resourceId: 'V1StGXR8Z5' }
}
});
The upload must use exactly the contentType the link came with, and must happen before expiresInSeconds runs out. The api helper sends text bodies, so upload the audio file itself from outside the script. Audio fields (greetingAudio, messageAudio, promptAudio, a voicemail's greetingAudio, a ring's waitAudio) also accept an https:// link to a file you host. When one is set, it plays instead of the matching text.
const { ok, data } = autessa.twilio.updateCallSettings({
configId: 'pH9nR3vC6b',
callSettings: {
recording: { save: true, announcement: 'This call may be recorded.' },
redaction: { enabled: true, redact: ['CARD_NUMBER', 'CARD_EXPIRY', 'CARD_CVV'], audioRedaction: 'TONE' },
limits: { maxDurationMinutes: 30, silenceTimeoutSeconds: 20 }
}
});
Settings sections are speech (voice and language), transcript and recording (each with an optional retentionDays), redaction, limits, callerInfo, screening (blocked callers), ai (interruptions, end-of-turn speed, hang-up phrases, key presses), and answeringMachine (detection on outgoing calls). Call Redaction costs $0.01 per call. Every field and range is in the call settings object reference.
const { data: options } = autessa.twilio.voiceOptions({});
options.languages.forEach(l => console.log(l.code, l.label));
autessa.twilio.updateCallSettings({
configId: 'pH9nR3vC6b',
callSettings: {
speech: { language: 'es-US' },
recording: { save: true, announcement: 'Esta llamada puede ser grabada.', retentionDays: 90 },
screening: { blockedNumbers: ['+15555550123'], rejectAnonymous: true },
ai: { endOfTurn: 'PATIENT', hangUpPhrases: ['Que tenga un buen día'] }
}
});
voiceOptions lists the languages and voices you can use in speech.
let after;
do {
const { ok, data } = autessa.twilio.getCalls({ configId: 'pH9nR3vC6b', limit: 50, after });
if (!ok) break;
data.calls.forEach(c => console.log(c.startedAt, c.direction, c.otherNumber, c.status, c.durationSeconds));
after = data.next;
} while (after);
Calls come newest first from your company's Phone calls table. Each call includes its caller info, status, who handled it, the transcript, and links to the recording and voicemail that stay valid for 10 minutes. data.tableId is the Phone calls table, so you can also query it directly with autessa.autessadb.
autessa.twilio.setAutomation({
configId: 'pH9nR3vC6b',
automation: 'EMAIL_VOICEMAILS',
enabled: true,
emails: ['frontdesk@example.com']
});
automation is TEXT_BACK_MISSED_CALLS (with smsMessage; the number must be able to text) or EMAIL_VOICEMAILS (with up to 5 emails). enabled: false turns it off without deleting the trigger behind it.
updateCallFlow, updateCallSettings, getCalls, setAutomation, audioUploadLink, and voiceOptions ship with the phone call controls release. The reference below lists them once the release is live.
Texts without AI from a script
Scripts can decide who answers a number's texts, read and reply to its shared inbox, and forward texts to your team. What each setting does is explained in Texts.
const { ok, data } = autessa.twilio.updateTextFlow({
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' }
}
});
if (ok) console.log(data.config.textFlow);
Pass textFlow: null to go back to the default: the agent the number sends calls to directly answers texts, or, without one, texts get no reply and wait in the inbox. STOP, START, and HELP are always handled first. Every field is in the text flow object reference.
const threads = autessa.twilio.listSmsThreads({ configId: 'pH9nR3vC6b', limit: 20 }).data.threads;
threads.forEach(t => console.log(t.otherNumber, t.lastDirection, t.lastBody, t.messageCount));
const first = threads[0];
const { data } = autessa.twilio.getSmsThread({ configId: 'pH9nR3vC6b', otherNumber: first.otherNumber, limit: 50 });
data.messages.forEach(m => console.log(m.sentAt, m.direction, m.handledBy, m.body));
if (first.lastDirection === 'INBOUND') {
autessa.twilio.sendSms({ configId: 'pH9nR3vC6b', to: first.otherNumber, body: 'Thanks, we got your message.' });
}
Pass next as after for more threads, or as before for older messages in a thread. Replies go out as the business number and are checked like any other text.
autessa.twilio.setAutomation({
configId: 'pH9nR3vC6b',
automation: 'FORWARD_TEXTS_SMS',
enabled: true,
phones: ['+14155550100']
});
FORWARD_TEXTS_SMS takes up to 5 phones, and FORWARD_TEXTS_EMAIL up to 5 emails. Forwarded texts are sent from the business number, so each phone must be allowed to receive texts from it (texting the number once from each phone is enough). Every text is also a row in your company's Text messages table; textLogTableId from getConfig is its id, so you can query it with autessa.autessadb.
updateTextFlow, listSmsThreads, getSmsThread, and the forwarding automations ship with the texting-without-AI release. The reference below lists them once the release is live.
autessa.twilio.configureRoutingMUTATE
autessa.twilio.configureRouting({ configId, routingType, directResourceType, directResourceId, routingConfig, locallyHostedStt, promptTemplateVariables, environmentVariables, initialMessage, initialMessagePrompt, conferenceParticipants, clientDisplayMessage })Route inbound calls for a company phone number to an agent, tool, or manager.
Sets how inbound voice calls to the phone number for configId are handled. With routingType=DIRECT, every call goes to one Autessa resource — set directResourceType (AGENT/TOOL/MANAGER) and directResourceId. With routingType=PRESS_DIGIT, callers hear a menu and are routed by the digit they press — supply routingConfig.digitToResourceMap. You must have access to every resource you route to. Optional fields tune the call: initialMessage / initialMessagePrompt for the greeting, promptTemplateVariables and environmentVariables for the target resource, conferenceParticipants for conference dial-out, and clientDisplayMessage for the browser client. Requires WRITE (or ADMIN) access to the configuration.
Request fields
- Name
configId- Type
- string (opaque id)
- Description
- References phone config by opaque id.
- Name
routingType- Type
- "DIRECT" | "PRESS_DIGIT"
- Description
- Name
directResourceType- Type
- "AGENT" | "TOOL" | "MANAGER"
- Description
- Name
directResourceId- Type
- string
- Description
- Name
routingConfig- Type
- TwilioRoutingConfig
- Description
- Name
locallyHostedStt- Type
- boolean
- Description
- Name
promptTemplateVariables- Type
- object
- Description
- Name
environmentVariables- Type
- object
- Description
- Name
initialMessage- Type
- string
- Description
- Name
initialMessagePrompt- Type
- string
- Description
- Name
conferenceParticipants- Type
- string[]
- Description
- Name
clientDisplayMessage- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
message- Type
- string
- Description
autessa.twilio.getAllConfigsREAD
autessa.twilio.getAllConfigs()List the company's Twilio phone configurations you can access.
Returns every phone configuration in the current company that you have access to, each with its number, routing, sharing, and active state. Takes no arguments.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
configs- Type
- PhoneConfigDto[]
- Description
autessa.twilio.getConfigREAD
autessa.twilio.getConfig({ configId })Fetch one Twilio phone configuration and your access level on it.
Returns the phone configuration for configId — its number, routing, sharing, and active state — along with your own permission level on it. Fails if you lack access.
Request fields
- Name
configId- Type
- string (opaque id)
- Description
- References phone config by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
config- Type
- PhoneConfigDto
- Description
- Name
permission- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
autessa.twilio.purchaseNumberMUTATE
autessa.twilio.purchaseNumber()Purchase a US phone number from Twilio for the company.
Searches for an available US phone number and purchases it from Twilio, creating an unconfigured phone configuration in the current company. HIGH risk: this buys a real phone number and incurs a recurring Twilio charge. The purchase is rejected if the company has reached its phone-number limit. Twilio picks the number — you cannot choose it here. After purchase, use configureRouting to point inbound calls at an agent, tool, or manager. Takes no arguments.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
configId- Type
- string (opaque id)
- Description
- References phone config by opaque id.
- Name
phoneNumber- Type
- string
- Description
- Name
twilioPhoneSid- Type
- string
- Description
- Name
message- Type
- string
- Description
autessa.twilio.releaseNumberMUTATE
autessa.twilio.releaseNumber({ configId })Release a company phone number back to Twilio and delete its configuration.
Releases the phone number for configId back to Twilio (stopping its recurring charge) and deletes the phone configuration from Autessa. HIGH risk: the number is given up and any inbound routing to it stops immediately; re-acquiring it is not guaranteed. Requires ADMIN access to the configuration.
Request fields
- Name
configId- Type
- string (opaque id)
- Description
- References phone config by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
message- Type
- string
- Description
autessa.twilio.voiceClient.identityREAD
autessa.twilio.voiceClient.identity({ userId })Resolve the Twilio voice-client identity string for a company member.
Returns the deterministic, opaque voice-client identity string for the given userId in the current company (used to address that user in browser voice calls). The target user must be a member of your company. This does not issue a token — use voiceClient.token for that.
Request fields
- Name
userId- Type
- string (opaque id)
- Description
- References user by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
identity- Type
- string
- Description
autessa.twilio.voiceClient.tokenMUTATE
autessa.twilio.voiceClient.token()Issue a Twilio voice access token for browser-based calling.
Generates a short-lived Twilio access token (a JWT with a voice grant) that lets the browser voice client place and receive calls as the current user's derived identity. Takes no arguments — the identity is derived from your session. Return the token to a browser client to initialise the Twilio Voice SDK.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
success- Type
- boolean
- Description
- Name
token- Type
- string
- Description
- Name
identity- Type
- string
- Description