API reference

Messaging

The log of SMS and WhatsApp messages the platform sent for a workspace, and the delivery-report webhook.

The platform sends text messages in three places: verification codes for verified numbers, the WhatsApp step of a workflow, and the send_sms function tool an agent can use during a call. Every message is recorded with its delivery status. There is no endpoint for sending an arbitrary message.

Operation	Method and path	Minimum role
List messages	`GET /messages`	admin
Receive a delivery report	`POST /messaging/webhooks/{provider}`	none

Limitation: The default provider for both SMS and WhatsApp is mock. It stores each message and sends nothing; numbers ending 0000 are made to fail. Adapters for Twilio and MSG91 exist, but they were written from the providers' public documentation and have only been run against local fakes. Send a real message from each provider's sandbox before relying on them.

List messages

GET /messages

Lists the workspace's SMS and WhatsApp messages with their delivery status, newest first. The text of a verification code is never shown here.

Auth: API key or session token. Role: admin and up.

Parameter	In	Type	Required	Description
`channel`	query	string	no	`sms` or `whatsapp`.
`purpose`	query	string	no	`otp` (verification code), `workflow` (workflow step) or `tool` (the `send_sms` tool).
`to`	query	string	no	A recipient number; it is normalised before matching.
`limit`	query	integer	no	1 to 200. Default 50.

Request

bash

curl "https://api.sevennadi.si/messages?channel=sms&limit=20" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{
  "providers": {"sms": "mock", "whatsapp": "mock"},
  "messages": [
    {
      "id": "6e2b1f0a-7c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "channel": "sms",
      "provider": "mock",
      "purpose": "tool",
      "to": "+919876500000",
      "body": "Your appointment is confirmed for Friday at 10:00.",
      "variables": {},
      "status": "delivered",
      "provider_message_id": "mock_1a2b3c4d",
      "execution_id": "0f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f",
      "created_at": "2026-10-13T09:00:00Z",
      "updated_at": "2026-10-13T09:00:04Z"
    }
  ]
}

Field	Meaning
`providers`	The operator's configured provider per channel.
`status`	`queued`, `sent`, `delivered`, `read` or `failed`. A late report never moves a status backwards.
`body`	The text. Left out for verification codes.
`template_name`, `language`, `variables`	Set for WhatsApp template messages.
`error`	Why a message failed.
`execution_id`, `workflow_execution_id`	The call or workflow run that caused the message.

Fields without a value are left out of each message.

Errors

Status	Message
400	`limit must be between 1 and 200`
403	`Your role (member) can't do this. It needs admin access; ask an owner or admin of the workspace.`

Receive a delivery report

POST /messaging/webhooks/{provider}

Called by the message provider, not by you. It updates the status of the messages named in the report.

Auth: none. A report is believed only if it passes the provider's own check: Twilio's X-Twilio-Signature, MSG91's secret in the URL (?key=..., because its reports are not signed), or the mock provider's HMAC in X-Mock-Signature.

Parameter	In	Type	Required	Description
`provider`	path	string	yes	`mock`, `twilio` or `msg91`.
(body)	body	bytes	yes	The provider's report (JSON or form-encoded), at most 256,000 bytes.

Request

bash

curl -X POST https://api.sevennadi.si/messaging/webhooks/twilio \
  -H "X-Twilio-Signature: SIGNATURE_FROM_THE_PROVIDER" \
  -d "MessageSid=SM00000000000000000000000000000000" \
  -d "MessageStatus=delivered"

Response 200 OK

json

{"received": true, "updated": 1}

updated is the number of messages whose status the report matched.

Errors

Status	Message
400	`Webhook rejected` (the check failed or the report is malformed)
404	`Not Found` (unknown provider)
413	`Payload too large`

Limitation: The MSG91 delivery-report format in particular has not been checked against a real report.