Twilio

Twilio is the canonical vendor behind AppEngine's Phone module, Voice module, and the SMS side of the Broadcast module. One Twilio integration unlocks all three. The connector handles SMS sends, inbound MMS, voice call origination and TwiML, IVR webhooks, recording webhooks, and phone-number provisioning.

Connect Twilio

Twilio uses Account SID + Auth Token (or API Key) for server auth. No OAuth required.

await fetch('/api/upstream/save-integration', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({
    type: 'twilio-provider',
    name: 'Twilio Production',
    credentials: {
      accountSid: 'AC...',
      authToken: '...',
      apiKeySid: 'SK...',
      apiKeySecret: '...',
    },
    publicConfig: {
      messagingServiceSid: 'MG...',
      defaultSenderNumber: '+15551234567',
    },
  }),
});

API Key + Secret is preferred over Auth Token for production — keys can be revoked individually without rotating the account password. messagingServiceSid is recommended for SMS sends because it handles sender pool selection automatically.

Phone numbers

Provisioning happens through the Phone module, which calls Twilio under the hood.

Buys a number, registers webhooks pointing at AppEngine's Connect endpoints, and stores the number against the org.

The webhooks Twilio posts to:

Voice webhooks return TwiML that drives the call (play prompt, gather digits, transfer). SMS webhooks deliver inbound messages to the platform inbox. Status webhooks track delivery state.

SMS

Application code sends SMS via Upstream:

await fetch('/api/upstream/call/twilio-provider/send-sms', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({
    to: '+15551234567',
    body: 'Your code is 123456',
    mediaUrl: ['https://cdn.../receipt.pdf'],
  }),
});

For broadcast campaigns, the Broadcast module routes through the same connector. Inbound SMS lands in the CRM inbox automatically — see GET /crm/inbox/conversations.

SMS routing rules

The Twilio connector includes a routing layer for inbound messages:

• auto-reply — send a templated response immediately
• go-to-flow — hand off to an automation flow
• fill-form — collect a sequence of fields via SMS prompts
• forward-sms — forward to a staff number
• ai-assistant — let an AI agent handle the conversation
• trigger-automation — fire a workflow
• create-lead — create a CRM lead from the message
• add-tag / opt-out / opt-in — manage the customer's tags

Configure rules per phone number via the phone module.

Voice and IVR

The Voice module's IVR orchestrator generates TwiML for inbound calls based on the configured flow. Supported actions in IVR flows that map to TwiML:

• transfer-phone, transfer-user, transfer-group, transfer-queue
• menu (Gather + Play)
• voicemail (Record)
• send-sms mid-call
• ai-assistant (route to AI voice agent)
• start-recording / pause-recording / resume-recording
• hangup

Outbound calls:

await fetch('/api/upstream/call/twilio-provider/make-call', {
  method: 'POST',
  headers: { orgid: ORG_ID, Authorization: `Bearer ${jwt}` },
  body: JSON.stringify({
    from: '+15551234567',
    to: '+15559876543',
    twimlUrl: 'https://api.appmint.io/automation/ivr/flow/welcome',
  }),
});

Realtime voice (AI agent)

The Voice module runs OpenAI Realtime API for AI voice agents. Twilio bridges the audio: a <Connect><Stream> TwiML block streams the call's audio to AppEngine's WebSocket gateway (SimpleVoiceGateway), which proxies to OpenAI and returns synthesised speech.

The connect setup is automated when you enable AI voice on a flow — the IVR orchestrator emits the right TwiML.

Softphone

Softphone presence lives in the Phone module:

Twilio's Voice SDK runs in the browser; the platform issues access tokens that authenticate the client to Twilio. Calls in/out flow through the softphone with presence updates persisted server-side.

Recordings and transcriptions

Recordings are stored on Twilio with public-by-default URLs. The platform stores only the SID and a reference to the recording. To retrieve audio, call the Twilio Recording API via Upstream — the connector returns a signed URL that the browser can stream.

Transcriptions can be enabled at recording-start; Twilio posts them via webhook when complete.

Common quirks

• TCPA compliance — outbound SMS to US numbers must include opt-out language. The Broadcast module enforces this on send.
• A2P 10DLC registration — required for US business SMS. Register your messaging service in the Twilio console; the integration reads the SID but doesn't drive the registration flow.
• Number portability — porting in/out is a manual Twilio process. The platform tracks ownership but doesn't initiate ports.