Send messages

Sending transactional texts today

The recommended interim pattern: your own SMS provider (Twilio, Telnyx, etc.) does the sending, and Speko's post-call webhook provides the trigger and the data. Your AI agent collects the details on the call; Speko extracts them into structured fields and POSTs them to you the moment the call ends.

1. Configure the post-call webhook with extraction fields

Dashboard: Settings → Webhooks, or via the API:

curl -X POST https://api.speko.dev/v1/webhooks \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SMS follow-up",
    "url": "https://your-server.com/speko/call-report",
    "events": ["call.report"],
    "allAgents": false,
    "agentIds": ["agent_123"],
    "extractionFields": [
      { "name": "visit_address", "type": "string",  "description": "Address the customer agreed we visit" },
      { "name": "visit_time",    "type": "string",  "description": "Agreed visit date/time, ISO 8601 with timezone" },
      { "name": "customer_phone","type": "string",  "description": "Customer mobile number in E.164 format" },
      { "name": "sms_consent",   "type": "boolean", "description": "Customer verbally agreed to receive SMS updates" }
    ]
  }'

Extraction field names match ^[a-zA-Z_][a-zA-Z0-9_]*$ (max 64 chars, up to 30 fields); types are string, number, boolean, or enum (with options).

2. Receive the call report

After every call, Speko POSTs a signed call.report to your URL:

{
  "type": "call.report",
  "call_id": "session_123",
  "agent_id": "agent_...",
  "summary": "Customer booked a visit for July 3 at 5 PM.",
  "outcome": "scheduled",
  "custom_data": {
    "visit_address": "123 Main St",
    "visit_time": "2026-07-03T17:00:00-07:00",
    "customer_phone": "+15551234567",
    "sms_consent": true
  },
  "transcript": { "entries": [ { "source": "user", "text": "..." } ] },
  "cost": { "usd": 0.042 },
  "created_at": "2026-07-01T22:41:03.000Z"
}

custom_data has one key per extraction field; values are null when the conversation gave no basis — always null-check before templating a message.

Delivery contract:

• Signed with Standard Webhooks headers webhook-id, webhook-timestamp, webhook-signature — verify with the workspace secret or the endpoint's custom secret.
• Respond 2xx within a few seconds and process asynchronously; slow responses count as failures.
• Failed deliveries are retried, and each retry carries the same webhook-id. Dedupe on that ID so a retry never double-sends a text.
• Redirects are not followed; configure the final URL.

3. Send the text through your provider

If custom_data.sms_consent is true and the fields are present, send the confirmation through your Twilio/Telnyx account from your registered number. Keep the send behind a small interface — when Speko's send API ships, it becomes a one-line swap.

4. Scheduled reminders

For reminders (for example 24h and 2h before an appointment), schedule jobs from the same webhook data. Each reminder can be a text from your provider — or a native AI reminder call:

curl -X POST https://api.speko.dev/v1/sessions/phone \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "agentId": "agent_...",
    "firstMessage": "Hi, this is MoonAI reminding you about your visit tomorrow at 5 PM.",
    "metadata": { "kind": "reminder", "booking_id": "bk_123" }
  }'

See the outbound calls API reference for all options. Cancel scheduled reminders when the booking is cancelled.

What's coming

The sending milestone adds a send endpoint on your registered numbers, an agent tool so the AI can text during or after a call, and inbound SMS webhooks. If SMS is important for your use case, tell the Speko team — real use cases move it up the roadmap.