Communications
Email, SMS, phone calls, scheduled outreach, and signed webhooks.
Overview
Galadri agents can communicate with users and outside contacts across email, SMS, and phone. In chat, your app sends a normal message to /v1/chat, and the agent decides whether communication is useful for the task. If your backend already knows it wants to send a message or place a call, use the Communications API instead.
Plain-text delivery surfaces
Email, SMS, and voice are delivery channels, not rich UI surfaces. Keep maps, cards, route displays, and saved-data cards in your app's chat UI. For messages sent outside the app, Galadri sends plain text or email HTML that makes sense in that channel.
Provider setup
Configure communication providers from the Credentials page. Credentials can be assigned as organization defaults or attached to specific agents.
Channels
| Field | Type | Description |
|---|---|---|
Email | SendGrid | Send emails and calendar invites from your verified sender. Inbound replies require SendGrid Inbound Parse on your reply subdomain. |
SMS | Twilio | Send SMS and MMS from a Twilio number that can send text messages. Inbound texting can be enabled on the same credential. |
Phone | Twilio + Galadri voice | Place AI phone calls through a voice-capable Twilio number. Galadri manages the AI voice runtime. |
Push and webhooks | HTTPS webhook | Send signed POST events to your backend so your app can deliver push notifications or custom channel updates. |
Credentials stay server-side
Provider API keys and tokens are encrypted at rest and resolved server-side. Do not put SendGrid, Twilio, or webhook signing secrets in client-side code.
Inbound modes
Email, SMS, and voice credentials can decide how Galadri handles replies or inbound contact on that provider identity.
| Field | Type | Description |
|---|---|---|
Outbound only | default | Galadri can send through this credential, but inbound messages or calls are not routed to an agent. |
Inbound for users only | user support | Known end users can reply or call in. Unknown senders can receive an optional configured response. |
Inbound + callbacks | external contacts | Outside businesses can reply or call back about active outreach. Galadri scopes callbacks by destination credential and outside contact, then active callback calls resume with the initiating agent while generic inbound calls use the credential handler. |
Inbound replies can be delayed so automated responses feel less abrupt. Email defaults to 60 seconds, SMS defaults to 20 seconds, and both can be set to 0 for instant replies.
Default agent routing
The credential's default inbound agent handles generic inbound messages, calls, and callback clarification when Galadri cannot safely pick one active case. Ambiguous voice callers start in a restricted identity-resolution state before account tools are available. Once a callback is matched to active outreach, the callback resumes with the agent that started that outreach, including that agent's prompt, model, and enabled communication tools.
Channel behavior
| Field | Type | Description |
|---|---|---|
Email and calendar | outbound + inbound | Send emails, send calendar invites, and cancel invites. Agent-authored emails include unsubscribe content and one-click unsubscribe headers, normal unsubscribe links open a confirmation page, provider click tracking is disabled so links stay direct, and replies such as unsubscribe update sender-recipient email preferences. |
SMS and MMS | outbound + inbound | Send short text updates and optional image attachments. Galadri checks sender-recipient SMS preferences before queueing, adds a first-contact SMS disclosure before the first outbound text from a sender to a recipient, tracks STOP and START preferences per sender-recipient pair, and checks the end user's SMS opt-in when texting their profile number. |
Phone calls | outbound + inbound | Place AI phone calls only from the agent's selected Twilio voice credential for confirmations, follow-ups, and service conversations. When calling the end user's profile number, Galadri checks call opt-in first, and clear requests such as never call me again are stored as sender-recipient call opt-outs. Agents can use enabled communication tools during calls, including calling, texting, emailing, or notifying another contact when that is the practical next step. Explicit user requests for post-call email or SMS updates record the matching opt-in before the callback objective is created. When outreach began from a chat session, chat follow-ups can continue that same thread with a new assistant update after the outside communication completes. |
Push events | webhook | Send a signed event to your backend for mobile push, in-app notifications, or any custom delivery channel you own. |
Scheduled communications
Schedules can trigger automated AI communication without a live chat request. Add an agent runtime time, prompt, and delivery channel to a schedule record, and Galadri will run the agent at the scheduled time and deliver the result through email, SMS, phone, or webhook.
Scheduled communications are useful for appointment reminders, maintenance follow-ups, renewal notices, and post-service check-ins. Execution history appears in the Console under scheduled logs.
Recurring schedules can also run monitoring or reporting prompts, such as checking for listing changes each week and emailing the result through an enabled email credential.
Scheduling fields live in the Data Model
The schedule fields for automation are documented in Data Model. Use those APIs when your backend needs to create or update scheduled communication records directly.
Webhooks
Webhook credentials require an HTTPS URL. When a webhook signing secret is configured, Galadri signs outbound webhook payloads with HMAC-SHA256 in X-Galadri-Signature. Verify the signature before trusting the payload.
Agent webhook usage has two modes. The default posts a chat.completed event after each successful Chat API run. The agent-selected mode exposes the webhook as a follow-up tool and keeps webhook available as a scheduled delivery channel alongside email, SMS, and phone calls.
Webhook headers
| Field | Type | Description |
|---|---|---|
Content-Type | header | application/json |
X-Galadri-Event | header | Event type for routing on your server. |
X-Galadri-Idempotency-Key | header | Stable delivery id when Galadri can provide one. Use it to dedupe retried follow-up webhooks. |
X-Galadri-Signature | header | HMAC-SHA256 signature when a signing secret is configured. |
Security and routing
- Inbound SendGrid and Twilio webhooks are signature-verified before Galadri processes the provider payload.
- Inbound callback routing is scoped to the destination credential and outside contact so one customer's replies cannot route into another customer's context.
- Matched external callbacks may use enabled communication tools for the same agentic workflow. Custom HTTP and MCP tools are not exposed in external callback runtimes.
- Voice callers whose phone number matches multiple accounts or callback cases must resolve identity inside the call before Galadri exposes account-specific tools.
- When an external callback resolves an active request that began in chat, Galadri can add the result to that same chat session and run a follow-up assistant turn so the user sees the update in the original thread.
- Unknown inbound senders are handled by the credential's configured mode and optional unknown-sender response.
- Communication preferences are tracked per organization, channel, sender, and recipient, so SMS, email, and phone opt-out behavior applies to end users and external contacts such as shops, drivers, and other third parties.
- Profile-level phone and email opt-in checks still apply when the target address matches the end user's saved profile phone number or email. A direct request such as email me after the call is treated as opt-in for that requested follow-up channel.
Next steps
- Communications API for direct email, SMS, and phone-call endpoints.
- Tools for the broader agent capability catalog.
- Schedules for schedule fields and automated communication records.