HelpfulAI
HelpfulAI ACP (agent communications)
HelpfulAI ACP (agent communications)

Inbound events

Serverhttps://mqqsoutginqsajeuttyp.supabase.co/functions/v1

Signed vendor webhooks that deliver SMS, voice and email to an avatar.

Resend inbound email webhook

POST
https://mqqsoutginqsajeuttyp.supabase.co/functions/v1
/avatar-inbound-email

Verifies the Svix signature, fetches the body from Resend and claims the message before acknowledging. Mail for a domain outside AVATAR_INBOUND_EMAIL_DOMAINS (default avatars.helpfulai.app) is acked and ignored. x-worker-secret selects the redrive lane.

Resend inbound email webhook › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: type, data
type = object · requires: claim_id
Properties for Variant 1:
A Resend webhook. Only `email.received` is claimed.
ResendWebhookEvent
type
​string · required
data
​object · required

Resend inbound email webhook › Responses

Claimed, duplicate, or skipped.

InboundReceipt
received
​boolean
claim_id
​string
duplicate
​boolean
status
​string
skipped
​string
error
​string · enum
Enum values:
claim_failed
fetch_failed
recovered
​boolean

Redrive lane only.

terminal
​boolean

Redrive lane only.

reason
​string

Redrive lane only.

Telnyx inbound SMS webhook

POST
https://mqqsoutginqsajeuttyp.supabase.co/functions/v1
/avatar-inbound-sms

Verifies the Ed25519 signature, journals instance controls and usage, then claims the message durably before acknowledging. Non-message.received events are acked and skipped. A request with x-worker-secret is the reaper's redrive of a stalled claim instead.

Telnyx inbound SMS webhook › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: data
type = object · requires: claim_id
Properties for Variant 1:
A Telnyx messaging webhook. Only `message.received` is ingested.
TelnyxMessagingEvent
​object · required

Telnyx inbound SMS webhook › Responses

Claimed, duplicate, or skipped.

InboundReceipt
received
​boolean
claim_id
​string
duplicate
​boolean
status
​string
skipped
​string
error
​string · enum
Enum values:
claim_failed
fetch_failed
recovered
​boolean

Redrive lane only.

terminal
​boolean

Redrive lane only.

reason
​string

Redrive lane only.

LiveKit SIP join/leave receipts for instance phone usage

POST
https://mqqsoutginqsajeuttyp.supabase.co/functions/v1
/avatar-phone-voice-webhook

Verifies the LiveKit webhook JWT in Authorization, then records voice usage for the inbound trunk.

LiveKit SIP join/leave receipts for instance phone usage › Request Body

A LiveKit webhook event; SIP participant joins and leaves are metered.
LivekitWebhookEvent
event
​string · required
createdAt
​integer
​object
​object

LiveKit SIP join/leave receipts for instance phone usage › Responses

Const value: OK
Phone numbersEmail