Skip to main content

RCS API (BETA) (1.0.0)

Download OpenAPI specification:Download

RCS API Description

The RCS API enables you to send rich, interactive messages using RCS for Business. Send text messages, rich cards with images, carousels, and interactive suggestions to engage users with modern messaging experiences.

Core Concepts

  • RCS for Business: Rich Communication Services for businesses, which lets you send interactive messages to users.
  • RCS Agents: Verified business identities that send RCS messages. Each agent has a unique ID and branding.
  • Rich Content: Messages can include text, images, videos, rich cards, carousels, and interactive suggestions (buttons, replies, actions).
  • Webhooks: Receive real-time notifications for message delivery, read receipts, and user responses.

Key Features

  • Send rich text messages with formatting and emojis
  • Send standalone rich cards with images, titles, descriptions, and suggestions
  • Send carousel cards with multiple scrollable items
  • Add interactive suggestions (quick replies, URL actions, dial actions, calendar events, location sharing)
  • Receive delivery and read receipts via webhooks
  • Handle user responses and interactions
  • Show the user that you are typing, and mark their messages read
  • Receive the user's typing and shared location via webhooks
  • Multi-agent support for different use cases (notifications, conversations)

Basic Workflow

  1. Send RCS Message: Your application makes a POST request to the /rcs/v1/messages endpoint with the message content, recipient phone number, and agent ID.
  2. Message Delivery: The API delivers the message over RCS for Business to the recipient's RCS-enabled device.
  3. Receive Events: Your application receives webhook notifications for delivery status, read receipts, and user responses.

Suggested Actions

Suggestions attach interactive buttons to a message or card. Each suggestion is either a reply (sends text back to your webhook) or an action (opens a URL, dials a number, views a location, asks for the user's location, or creates a calendar event).

Open URL action

open_url_action opens a web page when the user taps the button. By default the link opens in the device's browser. You can instead open it inside an in-app webview, which keeps the user in the messaging app.

Field Required Description
url yes The URL to open.
application no BROWSER (device browser) or WEBVIEW (in-app webview). Defaults to the device browser when omitted.
webview_view_mode no Webview size: FULL, HALF, or TALL. Only honored when application is WEBVIEW.
description no Accessibility description of the action.

Open in the device browser (default):

{
  "action": {
    "text": "Open website",
    "postback_data": "open_site",
    "open_url_action": {
      "url": "https://www.spirius.com"
    }
  }
}

Open in an in-app webview:

{
  "action": {
    "text": "Open in app",
    "postback_data": "open_webview",
    "open_url_action": {
      "url": "https://www.spirius.com",
      "application": "WEBVIEW",
      "webview_view_mode": "HALF",
      "description": "Open spirius.com in a half-screen webview"
    }
  }
}

The API is lenient: unknown fields in a request are dropped rather than rejected. Use the exact snake_case field names above. A misspelled or unsupported field is silently ignored (and logged server-side), so the option simply has no effect. Webview support and view modes ultimately depend on the recipient's RCS client.

Share location action

share_location_action asks the user to share their position. It has no fields: send an empty object.

{
  "action": {
    "text": "Share location",
    "postback_data": "share_location",
    "share_location_action": {}
  }
}
  • The position arrives at your webhook as rcs.in.location, with location.latitude and location.longitude.
  • Tapping the button first sends rcs.in.suggested.action with your postback_data. The position then arrives as rcs.in.location, which carries no postback_data. A user can also share a position without the button.
  • Android phones and iPhones (iOS 27.2) support it.
  • On an iPhone the user can add a comment. It arrives as a separate rcs.in.text right after rcs.in.location.

HTTP Response Codes

  • 200 OK: Successful GET requests (e.g., health checks).
  • 202 Accepted: Message or agent event accepted for delivery (async processing).
  • 400 Bad Request: Invalid request format, missing required fields, or validation errors.
  • 401 Unauthorized: Missing or invalid X-API-Key or X-Client-ID.
  • 403 Forbidden: Valid credentials but insufficient permissions, or invalid webhook signature.
  • 429 Too Many Requests: Rate limit exceeded (default: 100 requests/minute per client).
  • 500 Internal Server Error: Unexpected server error.
  • 501 Not Implemented: Requested feature not yet implemented (e.g., conversations agent).
  • 503 Service Unavailable: Service temporarily unavailable.

Errors

Every error is JSON (application/json) with code, message and, when the code has data, details. Branch on code; message is for people and may change. The shared codes (VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND, METHOD_NOT_ALLOWED, INTERNAL_ERROR, SERVICE_UNAVAILABLE) are described on developer.spirius.com/errors; the codes of this API are listed in the APIErrorResponse schema.

A validation error lists each failing input in details.errors:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "errors": [
      {"field": "message.suggestions[0].reply.text", "description": "String should have at most 25 characters", "reason": "string_too_long"}
    ]
  }
}

A missing or wrong X-API-Key or X-Client-ID always answers 401 with UNAUTHORIZED and the message Invalid or missing credentials., before the request is validated.

HTTP Headers

Authentication

The API uses dual-header authentication with API key and client ID:

X-API-Key: your_api_key_here
X-Client-ID: your_client_id
Content-Type: application/json

Example:

POST /rcs/v1/messages HTTP/1.1
Host: api.example.com
X-API-Key: rcs_live_abc123xyz
X-Client-ID: acme_corp
Content-Type: application/json

Limitations

Message Content

  • Text Messages: Up to 3072 characters
  • Rich Card Title: Up to 200 characters
  • Rich Card Description: Up to 2000 characters
  • Suggestions per Message: Maximum 4 suggestions per card, 11 per carousel
  • Carousel Cards: 2-10 cards per carousel

Rate Limits

  • Default: 100 requests per second per client
  • Scope: Limits applied per X-Client-ID
  • Exceeding the rate limit returns 429 Too Many Requests

Character Encoding

  • All request bodies must be UTF-8 encoded JSON
  • RCS supports full Unicode including emojis
  • Rich text formatting is supported (bold, italic, etc.)

Phone Number Format

Phone numbers must be in E.164 format:

  • Format: +[country_code][number]
  • Example: +46701234567 (Sweden), +12025551234 (USA)
  • Required: Leading + and country code
  • No spaces or special characters

Media Files

  • Images: JPEG, PNG (recommended max 2MB)
  • Videos: MP4, 3GP (recommended max 10MB)
  • Thumbnails: Automatically generated or provide custom URL
  • Hosting: Media files must be publicly accessible via HTTPS

RCS Events (Webhooks)

The API sends RCS Events to your configured webhook URL when users interact with your messages or when message status changes.

Event Types

Inbound (User Messages):

  • rcs.in.text: User sent a text message
  • rcs.in.file: User sent a file (image, video, document)
  • rcs.in.suggested.reply: User clicked a reply suggestion button
  • rcs.in.suggested.action: User clicked an action suggestion (URL, dial, location)
  • rcs.in.typing: User is typing. One attempt per webhook, never redelivered
  • rcs.in.location: User shared a location

Outbound (Message Status):

  • rcs.out.delivered: Message successfully delivered to device
  • rcs.out.read: User opened/read the message
  • rcs.out.failed: Message failed to send
  • sms.out.sent: Message fell back to SMS and the SMS was accepted (SMS fallback is not yet enabled)

Subscription Events:

  • rcs.sub.subscribed: User subscribed in their messaging app
  • rcs.sub.unsubscribed: User unsubscribed (includes STOP words)

Test Events (Dry Run):

  • test.rcs.out.delivered: Simulated delivery event for testing

Complete Documentation

For complete webhook documentation including event payload structure, all field descriptions, example payloads, retry behavior, and integration guide, see the RCS Events section in the API reference.

Delivery timeout

Set timeout_seconds on POST /rcs/v1/messages to limit how long the RCS message may take to reach the phone: 6 to 86400 seconds (24 hours), counted from when the API accepts the request. Without it the message has no timeout.

When the timeout passes before the message is delivered, it is withdrawn:

  • With sms_fallback, the recipient gets the SMS and your webhook gets sms.out.sent with reason RCS_EXPIRED.
  • Without sms_fallback, your webhook gets rcs.out.failed with reason RCS_EXPIRED.

Corner cases:

  • Very rarely the withdrawal fails. A message with message_traffic_type AUTHENTICATION and sms_fallback still gets the SMS, so the recipient may receive both. Any other message gets no event, because the RCS message may still arrive.
  • Very rarely the RCS message is delivered although it was withdrawn, or no outcome is reported at all. You may then get rcs.out.delivered as well, or no outcome event.
  • The SMS is sent once the withdrawal is reported, so it can arrive after the timeout.
  • In rare cases rcs.out.failed with RCS_EXPIRED arrives without client_message_id. Match it on message_id. No SMS was sent then, even if the request set sms_fallback.
  • A dry run ignores timeout_seconds.

Live conversation

POST /rcs/v1/agent-events sends the user a typing indicator or a read receipt. The call is fire and forget: it answers 202 once the request is valid, sends the event to Google once with no retry and no queue, and does not report Google's outcome.

  • Typing: send TYPING while you prepare an answer. The indicator lasts about 20 seconds; send TYPING again while you work to keep it showing. Your next message clears it.
  • Read: send READ with the message_id of the user's message, taken from its inbound event. It also marks the user's earlier messages read. Nothing is marked read unless you send READ.
  • The user's typing arrives as rcs.in.typing. Each webhook gets one attempt, with no retry, and the event is never redelivered. It can arrive after the user's next message, so ignore an rcs.in.typing older than the latest message you have from that user.
  • The user's position arrives as rcs.in.location (see Share location action).

Android phones show the typing dots and the read receipt. iPhones do not support either as of iOS 27.2.

User-started conversations

A user can start a conversation with your agent from a link or a QR code. Their first message reaches your webhook like any other inbound message.

The link opens a chat with your agent in Google Messages, optionally with pre-filled text:

sms:+46701234567?service_id=your_agent_id%40rbm.goog&body=Hello%20SPRING26
Part Required Description
+46701234567 no Fallback number in E.164 format, or a short code. A user whose device cannot open the chat is sent there.
service_id yes Your agent_id followed by @rbm.goog, URL-encoded (%40).
body no Pre-filled text, URL-encoded (%20 for a space). The user can edit it before tapping send. A campaign code here tells you which link or poster the conversation came from.

Without a fallback number the agent id is the address: sms:your_agent_id%40rbm.goog?body=Hello.

  • The chat opens only when Google Messages has RCS chats turned on and your agent is launched on the user's carrier, or the number is a registered tester (/rcs/v1/testers). Otherwise the user goes to the fallback number, or sees an error when the link has none.
  • The link must be tapped: put it behind a button, a link or a QR code. Typed into a browser address bar it does not open.
  • The link cannot carry suggested replies or actions, only text.

QR code

Encode an HTTPS short link that redirects to the sms: link, not the sms: link itself. Some phone camera apps drop service_id from a raw sms: QR code. A short link also lets you change the target without reprinting.

What reaches your webhook

  • The message arrives as rcs.in.text with agent_id, sender_phone_number and text. The text is what the user sent, including any pre-filled campaign code they kept.
  • While the user types, your webhook gets rcs.in.typing (see Live conversation).
  • To answer, send POST /rcs/v1/messages with recipient set to sender_phone_number and the same agent_id.

Agent Types

The API supports multiple RCS agents for different use cases:

  • Notifications Agent: One-way messages (alerts, updates, confirmations)
  • Conversations Agent: Two-way conversations (customer support, inquiries)

Specify the agent using the agent_id field in your request.

Health

API health check endpoints.

API Liveness Check

Liveness check endpoint that verifies the API process is running.

This endpoint is used by Kubernetes liveness probes to determine if the pod should be restarted. It returns 200 as long as the process is alive.

Returns: HealthResponse: Status information indicating the API is alive

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

API Readiness Check

Readiness check endpoint that verifies the API can handle requests.

This endpoint is used by Kubernetes readiness probes to determine if the pod should receive traffic. It checks the service's critical dependencies.

Returns 200 only when all dependencies are available.

Returns: HealthResponse: Status information indicating the API is ready JSONResponse: 503 response if dependencies are not available

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

RCS Events

Rcs Event Webhook Webhook

RCS Event Notification

The RCS API sends RCS Events to your configured webhook URL when users interact with your RCS messages or when message delivery status changes.

Event Types

Category Event Type Description Additional Info
Inbound rcs.in.text User sent a text message Freeform text from user
Inbound rcs.in.file User sent a file (image, video, document) Contains file URI and metadata
Inbound rcs.in.suggested.reply User clicked a reply suggestion button Quick reply in conversation
Inbound rcs.in.suggested.action User clicked an action suggestion Opens URL, dials phone, shares location, etc.
Inbound rcs.in.typing User is typing One attempt per webhook, no retry, never redelivered
Inbound rcs.in.location User shared a location Contains location.latitude and location.longitude
Outbound rcs.out.delivered Message successfully delivered to user's device Reliable delivery confirmation
Outbound rcs.out.read User opened and read the message Reliable read confirmation
Outbound rcs.out.failed Message failed to send When delivery fails due to error or network issue
Outbound sms.out.sent Message fell back to SMS and the SMS was accepted Only for messages sent with sms_fallback; carries sms_transaction_id and reason
Subscription rcs.sub.subscribed User subscribed in their messaging app or other channels User explicitly consents
Subscription rcs.sub.unsubscribed User unsubscribed in their messaging app, stop words, or other channels Must honor immediately
Test (Dry Run) test.rcs.out.delivered Simulated delivery event for testing One event per dry run message

Important Notes

  • Stop Words: When users send stop words (STOP, BAJA, parar, etc.) as text messages, they are mapped to rcs.sub.unsubscribed events. Your webhook may receive both the text message (rcs.in.text) and the unsubscribe event (rcs.sub.unsubscribed). Handle these idempotently.

Dry Run Testing

When sending messages with dry_run: true, no actual RCS message is sent. Instead, the API simulates the complete message flow and generates a test event to your webhook:

  • One test event is generated for each dry run message
  • test.rcs.out.delivered is sent (simulating successful delivery)
  • This event has the same structure as real events but with test.rcs.out. prefix
  • Use dry run mode to test your webhook integration without sending real messages

Webhook Configuration

Setting Value Notes
HTTP Method POST All webhook events are sent via POST
Content-Type application/json Event payload in JSON format
Authentication HMAC-SHA256 signature (always included) Signature sent in X-Webhook-Signature header - validation optional but recommended
Configuration Per-agent webhooks Use Webhook Management API to configure
Required Response HTTP 200, 201, 202 or 204 Any other status (4xx included), a redirect, a timeout or a connection error is a failed delivery
Timeout 10 seconds Endpoint must respond within 10 seconds

Event Payload Fields

Field Type Description Always Present
event_type string Type of event (see Event Types table above) All events
agent_id string RCS agent identifier (e.g., 'spirius_notifications_agent') All events
send_time string Event timestamp in ISO 8601 format All events
event_id string Unique identifier for this specific event occurrence (format: evt_*) All events - use for deduplication
message_id string Message identifier linking events to their message For message-related events
client_message_id string Optional client-provided ID from original send request Only if provided by client
sender_phone_number string User's phone number in E.164 format When available
text string Plain text content of message For text messages
content_message object Structured message content (suggestion responses) For button clicks
user_file object File information (payload + thumbnail) For file uploads
location object Shared position (latitude, longitude) For rcs.in.location

Retry Behavior

Each webhook is delivered to and retried on its own: a failing webhook never delays or blocks delivery to the agent's other webhooks. The webhook's delivery_status and delivery_status_since show where it stands.

Scenario Behavior
Successful delivery Response 200, 201, 202 or 204. No retry
Failed delivery Any other status (4xx included), a redirect, a timeout or a connection error. After a few immediate attempts the event is queued for retry and the webhook becomes failing
Retry schedule 1 minute after the failure, then after 5, 15, 30, 60 and 120 minutes, with a last attempt when the event's retry period ends
Retry period Each event is retried for up to 3 hours from when it was first queued, then dropped. An event the endpoint keeps rejecting while it takes others is dropped after those 3 hours too
While failing New events are queued without an immediate attempt and retried with the others
Recovery Any successful delivery (a retry, a probe, or a successful POST /v1/webhooks/{webhook_id}/test) makes the webhook healthy and sends its queued events at once
Dead webhook No delivery succeeded in the 3 hours from the webhook's first failed delivery. The webhook becomes dead, its queued events are discarded, and new events are dropped, except one event an hour that is sent as a probe. Run the test endpoint once your endpoint is fixed to recover at once
URL change or re-enable The webhook becomes healthy. Queued events are sent to the current URL, signed with the current secret
Webhook deleted, disabled or no longer subscribed Its queued events are dropped
Queue limit A failing webhook's queue has a size limit; events beyond it are dropped
Delivery guarantee At least once: the same event can arrive more than once. Use event_id to detect duplicates
Ordering Not guaranteed: a retried event can arrive after newer events
User typing (rcs.in.typing) One attempt, never queued or retried, not sent to a dead webhook, and no effect on the delivery status. It can arrive after the user's next message: ignore one older than the latest message you have

Implementation Best Practices

  1. Respond immediately - Return HTTP 200, 201, 202 or 204 as soon as you receive the event
  2. Process asynchronously - Queue events for background processing
  3. Implement idempotency - Use event_id to detect and ignore duplicate deliveries
  4. Log failures - Track processing errors for manual review
  5. Monitor availability - Ensure your webhook endpoint is always accessible

Security & Authentication

HMAC Signature:

  • Every webhook event includes an X-Webhook-Signature header
  • Signature is the lower-case hex HMAC-SHA256 of the raw request body using your webhook secret
  • Secret is auto-generated when you create the webhook (returned in response)
  • You can regenerate the secret anytime using the /regenerate-secret endpoint
  • Validation is optional - you can choose to validate or ignore the signature

Security Best Practices:

  1. Use HTTPS - Production webhooks must use HTTPS URLs
  2. Validate signatures (recommended) - Verify HMAC-SHA256 signature to ensure events are from Spirius
  3. Validate structure - Check event payload matches expected schema
  4. Respond quickly - Fast responses prevent unnecessary retries
  5. IP whitelisting - Consider restricting access to Spirius webhook sources

Python Signature Verification Example:

import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException, status

def verify_webhook_signature(payload_bytes: bytes, signature: str, secret: str) -> bool:
    '''
    Verify HMAC-SHA256 signature from X-Webhook-Signature header.
    
    Args:
        payload_bytes: Raw request body bytes
        signature: Value from X-Webhook-Signature header
        secret: Your webhook secret from webhook creation/regeneration
        
    Returns:
        True if signature is valid, False otherwise
    '''
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    
    # Use compare_digest to prevent timing attacks
    return hmac.compare_digest(expected_signature, signature)

# Example usage in FastAPI
app = FastAPI()

@app.post('/webhook')
async def webhook(request: Request):
    signature = request.headers.get('X-Webhook-Signature')
    payload_bytes = await request.body()
    
    # Validate signature (optional but recommended): reject a missing or wrong one
    if not signature or not verify_webhook_signature(payload_bytes, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail='Invalid signature')
    
    # Process event
    event = await request.json()
    # ... your business logic here ...
    
    return {'status': 'received'}

Note on Unsubscribe Events

When users unsubscribe, you may receive both an unsubscribe event AND a text message with a keyword (STOP, BAJA, parar, etc.). Ensure your system handles these idempotently to avoid duplicate processing.

Example Payloads

User Text Message

{
  "event_type": "rcs.in.text",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:15:30.995131Z",
  "event_id": "evt_a1b2c3d4e5f678901234",
  "sender_phone_number": "+1234567890",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Hello, I have a question"
}

File Upload (User Sent Image/Document)

{
  "event_type": "rcs.in.file",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-11-04T17:41:04.790512Z",
  "event_id": "evt_9f8e7d6c5b4a32109876",
  "sender_phone_number": "+34693363516",
  "message_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "user_file": {
    "payload": {
      "mime_type": "image/heic",
      "file_size_bytes": 910755,
      "file_name": "IMG_1644.heic",
      "file_uri": "https://rcs-copper-eu.googleapis.com/blob/..."
    },
    "thumbnail": {
      "mime_type": "image/jpeg",
      "file_size_bytes": 8249,
      "file_uri": "https://rcs-copper-eu.googleapis.com/blob/..."
    }
  }
}

User Shared Location

{
  "event_type": "rcs.in.location",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-11-04T17:52:10.123456Z",
  "event_id": "evt_4d5e6f7a8b9c0d1e2f3a",
  "sender_phone_number": "+1234567890",
  "message_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "location": {
    "latitude": 59.3293,
    "longitude": 18.0686
  }
}

User Typing

{
  "event_type": "rcs.in.typing",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-11-04T17:52:05.000000Z",
  "event_id": "evt_5e6f7a8b9c0d1e2f3a4b",
  "sender_phone_number": "+1234567890"
}

Reply Suggestion (User Clicked Quick Reply)

{
  "event_type": "rcs.in.suggested.reply",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:18:00.000000Z",
  "event_id": "evt_fedcba9876543210abcd",
  "sender_phone_number": "+1234567890",
  "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "content_message": {
    "suggestion_response": {
      "postback_data": "action_confirm",
      "text": "Confirm",
      "type": "REPLY"
    }
  }
}

Action Button (User Clicked Link/URL)

{
  "event_type": "rcs.in.suggested.action",
  "agent_id": "spirius_notifications_tggofuud_agent",
  "send_time": "2025-11-04T17:49:06.726341Z",
  "event_id": "evt_123456789abcdef01234",
  "sender_phone_number": "+34693363516",
  "message_id": "8ca1552a-b8a8-4068-bbf4-1046760224f4",
  "content_message": {
    "suggestion_response": {
      "postback_data": "book_nature_event",
      "text": "Book now",
      "type": "ACTION"
    }
  }
}

Message Delivered Event

{
  "event_type": "rcs.out.delivered",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:16:00.123456Z",
  "sender_phone_number": "+1234567890",
  "event_id": "evt_d1e2f3a4b5c6d7e8f9a0",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_message_id": "client_msg_001",
  "create_time": "2025-10-12T15:16:00.123456Z"
}

Message Read Event

{
  "event_type": "rcs.out.read",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:17:30.456789Z",
  "sender_phone_number": "+1234567890",
  "event_id": "evt_e1f2a3b4c5d6e7f8a9b0",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_message_id": "client_msg_001",
  "create_time": "2025-10-12T15:17:30.456789Z"
}

Message Failed Event

{
  "event_type": "rcs.out.failed",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:18:00.000000Z",
  "event_id": "evt_f1a2b3c4d5e6f7a8b9c0",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_message_id": "client_msg_001",
  "create_time": "2025-10-12T15:18:00.000000Z"
}

rcs.out.failed carries a reason: RECIPIENT_NOT_RCS_CAPABLE (no RCS and no sms_fallback), RCS_REJECTED (Google refused the RCS message; reported with or without sms_fallback, and no SMS is sent),RCS_EXPIRED (the delivery timeout passed and no SMS was sent), SMS_FALLBACK_REJECTED (the fallback SMS was refused as invalid) or SMS_FALLBACK_FAILED (the fallback SMS failed for another reason).

SMS Fallback Sent Event (SMS fallback is not yet enabled)

{
  "event_type": "sms.out.sent",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:18:00.000000Z",
  "event_id": "evt_a1f2b3c4d5e6f7a8b9c0",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_message_id": "client_msg_001",
  "sender_phone_number": "+1234567890",
  "sms_transaction_id": "28fc2e4a-abc2-4942-9eec-a61f9dcfb54d",
  "reason": "RECIPIENT_NOT_RCS_CAPABLE",
  "create_time": "2025-10-12T15:18:00.000000Z"
}

User Subscribed Event (messaging app)

{
  "event_type": "rcs.sub.subscribed",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:21:00.000000Z",
  "event_id": "evt_1a2b3c4d5e6f7a8b9c0d",
  "create_time": "2025-10-12T15:21:00.000000Z"
}

User Unsubscribed Event (messaging app)

{
  "event_type": "rcs.sub.unsubscribed",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:20:00.000000Z",
  "event_id": "evt_2b3c4d5e6f7a8b9c0d1e",
  "create_time": "2025-10-12T15:20:00.000000Z"
}

Test Delivered Event (Dry Run Mode)

{
  "event_type": "test.rcs.out.delivered",
  "agent_id": "spirius_notifications_agent",
  "send_time": "2025-10-12T15:24:00.000000Z",
  "event_id": "evt_3c4d5e6f7a8b9c0d1e2f",
  "message_id": "9b2d5c8e-1234-4abc-9def-0123456789ab",
  "client_message_id": "client_msg_test_001",
  "create_time": "2025-10-12T15:24:00.000000Z"
}
Request Body schema: application/json
required
agent_id
required
string (Agent Id)

Agent identifier (e.g., 'spirius_notifications_agent')

send_time
required
string (Send Time)

Event send time (RFC3339)

Client Message Id (string) or Client Message Id (null) (Client Message Id)

Optional client-provided message ID from original request

Any of
string (Client Message Id)

Optional client-provided message ID from original request

ContentMessage (object) or null

Structured message content

Any of
SuggestionResponse (object) or null

Suggestion response

Text (string) or Text (null) (Text)

Text content

property name*
additional property
any
Create Time (string) or Create Time (null) (Create Time)

Event creation time (RFC3339)

Any of
string (Create Time)

Event creation time (RFC3339)

Event Id (string) or Event Id (null) (Event Id)

Unique Spirius event identifier for deduplication (format: evt_*) - present for all events

Any of
string (Event Id)

Unique Spirius event identifier for deduplication (format: evt_*) - present for all events

Event Type (string) or Event Type (null) (Event Type)

Event type, such as rcs.in.text, rcs.out.delivered or rcs.sub.unsubscribed. See the RCS Events section for the full list.

Any of
string (Event Type)

Event type, such as rcs.in.text, rcs.out.delivered or rcs.sub.unsubscribed. See the RCS Events section for the full list.

EventLocation (object) or null

Position the user shared (rcs.in.location only)

Any of
latitude
number (Latitude)
longitude
number (Longitude)
property name*
additional property
any
Message Id (string) or Message Id (null) (Message Id)

Message identifier for tracking

Any of
string (Message Id)

Message identifier for tracking

Reason (string) or Reason (null) (Reason)

On rcs.out.failed, why the message reached the recipient on no channel: RECIPIENT_NOT_RCS_CAPABLE, RCS_REJECTED, RCS_EXPIRED, SMS_FALLBACK_REJECTED or SMS_FALLBACK_FAILED. On sms.out.sent, why the SMS was sent: RECIPIENT_NOT_RCS_CAPABLE or RCS_EXPIRED. New values may be added.

Any of
string (Reason)

On rcs.out.failed, why the message reached the recipient on no channel: RECIPIENT_NOT_RCS_CAPABLE, RCS_REJECTED, RCS_EXPIRED, SMS_FALLBACK_REJECTED or SMS_FALLBACK_FAILED. On sms.out.sent, why the SMS was sent: RECIPIENT_NOT_RCS_CAPABLE or RCS_EXPIRED. New values may be added.

Sender Phone Number (string) or Sender Phone Number (null) (Sender Phone Number)

User's phone number in E.164 format

Any of
string (Sender Phone Number)

User's phone number in E.164 format

Sms Transaction Id (string) or Sms Transaction Id (null) (Sms Transaction Id)

The SMS gateway's transaction id of a fallback SMS (sms.out.sent only)

Any of
string (Sms Transaction Id)

The SMS gateway's transaction id of a fallback SMS (sms.out.sent only)

Text (string) or Text (null) (Text)

Message text content

Any of
string (Text)

Message text content

UserFile (object) or null

File uploaded by user (images, videos, documents)

Any of
required
object (FileInfo)

Main file information

FileInfo (object) or null

Thumbnail for images/videos

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "agent_id": "spirius_notifications_agent",
  • "event_id": "evt_a1b2c3d4e5f678901234",
  • "event_type": "rcs.in.text",
  • "message_id": "550e8400-e29b-41d4-a716-446655440000",
  • "send_time": "2025-10-12T15:15:30.995131Z",
  • "sender_phone_number": "+1234567890",
  • "text": "Hello, I have a question"
}

Response samples

Content type
application/json
null

RCS Messaging

Send Agent Event

Show the user that the business is typing, or mark one of the user's messages as read.

  • TYPING shows the typing indicator for about 20 seconds. Send it again to keep it showing. Your next message clears it.
  • READ marks the user's message message_id as read. Take message_id from the inbound event (rcs.in.text, rcs.in.file and the other rcs.in.* types). It also marks the user's earlier messages read. Nothing is marked read unless you send READ.
  • 202 means the event was accepted for delivery; the API does not report whether the phone showed it.
  • The event is sent once, with no retry and no queue. A recipient without RCS is not reported back. Google ignores an unknown message_id without an error.
header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
agent_id
required
string (Agent Id)

The RCS agent identifier.

recipient
required
string (Recipient)

The user's phone number in E.164 format.

type
required
string (Type)
Enum: "TYPING" "READ"

TYPING shows the typing indicator for about 20 seconds. READ marks the message message_id as read.

Message Id (string) or Message Id (null) (Message Id)

The message_id of the user's message, from its inbound event. Required for READ, rejected for TYPING.

Any of
string (Message Id)

The message_id of the user's message, from its inbound event. Required for READ, rejected for TYPING.

Responses

Request samples

Content type
application/json
Example
{
  • "agent_id": "spirius_notifications_agent",
  • "message_id": "550e8400-e29b-41d4-a716-446655440000",
  • "recipient": "+46701234567",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "code": "VALIDATION_ERROR",
  • "details": {
    },
  • "message": "Request validation failed"
}

Send Message

Send a rich RCS message asynchronously using a specific RCS agent.

This endpoint requires X-API-Key header authentication. It validates the request, accepts the message for asynchronous delivery, and returns immediately.

Async Processing:

  • Message is accepted and delivered asynchronously
  • API returns immediately (< 50ms) with a message_id
  • Actual delivery happens within seconds

Message Tracking:

  • The message_id in the response is your tracking ID for this message
  • This ID will be included in all webhook events (delivery, read, user responses)
  • Optionally provide client_message_id to correlate with your own system
  • Both IDs will be included in webhook events for easy correlation
header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
recipient
required
string (Recipient)

The user's phone number in E.164 format.

agent_id
required
string (Agent Id)

The RCS agent identifier.

required
object (rcs_api__models__rbm_message_models__ContentMessage)
ContentInfo (object) or null
RichCard (object) or null
Array of Suggestions (objects) or Suggestions (null) (Suggestions)
Text (string) or Text (null) (Text)
Client Message Id (string) or Client Message Id (null) (Client Message Id)

Optional client-provided message ID for tracking in your system. Will be included in webhook events.

Any of
<= 256 characters
string (Client Message Id) <= 256 characters

Optional client-provided message ID for tracking in your system. Will be included in webhook events.

dry_run
boolean (Dry Run)
Default: false

When true, simulates message sending without delivering the message. Generates test.rcs.out.delivered events for integration testing.

Message Traffic Type (string) or Message Traffic Type (null) (Message Traffic Type)

Traffic type to categorize the message. Defaults to agent's use case if not specified.

Any of
string (Message Traffic Type)
Enum: "AUTHENTICATION" "TRANSACTION" "PROMOTION" "SERVICEREQUEST" "ACKNOWLEDGEMENT" "MESSAGE_TRAFFIC_TYPE_UNSPECIFIED"

Traffic type to categorize the message. Defaults to agent's use case if not specified.

SmsFallback (object) or null

Optional SMS sent instead when the recipient cannot be reached over RCS. SMS fallback is not yet enabled; until it is, a request carrying this field is refused with 400.

Any of
text
required
string (Text) [ 1 .. 1530 ] characters

The SMS text, not blank. At most 1530 characters; a text that needs more than 10 SMS parts is truncated by the SMS gateway.

sender
required
string (Sender) ^([A-Za-z0-9]{1,11}|\+[1-9][0-9]{1,14})$

An alphanumeric sender name of at most 11 characters, or an E.164 number.

Timeout Seconds (integer) or Timeout Seconds (null) (Timeout Seconds)

How long, in seconds, the RCS message may take to reach the phone, counted from when the request is accepted. When it passes undelivered, the message is withdrawn and the SMS fallback is sent, or the webhook gets rcs.out.failed with reason RCS_EXPIRED. Omitted means no timeout. Ignored on a dry run.

Any of
[ 6 .. 86400 ]
integer (Timeout Seconds) [ 6 .. 86400 ]

How long, in seconds, the RCS message may take to reach the phone, counted from when the request is accepted. When it passes undelivered, the message is withdrawn and the SMS fallback is sent, or the webhook gets rcs.out.failed with reason RCS_EXPIRED. Omitted means no timeout. Ignored on a dry run.

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "client_message_id": "string",
  • "dry_run": false,
  • "message": {
    },
  • "message_traffic_type": "AUTHENTICATION",
  • "recipient": "string",
  • "sms_fallback": {
    },
  • "timeout_seconds": 6
}

Response samples

Content type
application/json
{
  • "client_message_id": "string",
  • "message_id": "string"
}

Device Capabilities

Check device RCS capability

Check if a phone number supports RCS messaging and retrieve supported features.

**Caching Strategy:**
- Results are cached per agent (shared across all clients using that agent)     - RCS-supported devices: 7 day cache TTL
- Non-RCS devices: 24 hour cache TTL
- Use `force_refresh=true` to bypass cache

**Use Cases:**
- Pre-send capability check for campaign planning
- Testing specific devices during development
- Integration workflows that route based on capability

**Note:** When sending messages via `/messages`, capability checking happens 
automatically in the background - you don't need to call this endpoint explicitly 
for every message send.
path Parameters
phone
required
string (Phone)
Examples: +1234567890

Phone number in E.164 format (e.g., +1234567890)

query Parameters
agent_id
required
string (Agent Id)
Examples: agent_id=notifications

RCS agent ID to use for capability check

force_refresh
boolean (Force Refresh)
Default: false

Force fresh capability check, bypassing cache. Useful for testing.

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "cached": true,
  • "checked_at": "2025-10-13T10:30:00Z",
  • "features": [
    ],
  • "phone_number": "+1234567890",
  • "rcs_supported": true
}

Tester Management

List Testers

List all testers for a specific agent.

This endpoint retrieves all test devices registered for the specified agent. Only testers associated with agents assigned to the authenticated client are accessible.

Query Parameters:

  • agent_id: Required. The agent ID to list testers for.

Returns:

  • 200 OK: List of testers
  • 401 Unauthorized: Invalid authentication
  • 403 Forbidden: Client not authorized for this agent
  • 502 Bad Gateway: the messaging platform returned an error (UPSTREAM_ERROR)
query Parameters
agent_id
required
string (Agent Id)

Agent ID to list testers for

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "testers": [
    ],
  • "total_count": 0
}

Add Tester

Add a tester to an agent.

This endpoint registers a test device for the specified agent. The device owner will receive an invitation to become a tester.

Request Body:

  • phone_number: Phone number in E.164 format (e.g., +1234567890)
  • agent_id: Agent ID to add the tester to
  • label: Optional label for quick identification (e.g., 'János iOS')

Returns:

  • 201 Created: Tester added
  • 400 Bad Request: Invalid request
  • 401 Unauthorized: Invalid authentication
  • 409 Conflict: Tester already exists
  • 502 Bad Gateway: the messaging platform returned an error (UPSTREAM_ERROR)
header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
phone_number
required
string (Phone Number) ^\+[1-9][0-9]{1,14}$

Phone number in E.164 format (e.g., +1234567890)

agent_id
required
string (Agent Id)

Agent ID to add the tester to

Label (string) or Label (null) (Label)

Optional label for this tester (e.g., 'John iOS')

Any of
<= 25 characters
string (Label) <= 25 characters

Optional label for this tester (e.g., 'John iOS')

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "label": "string",
  • "phone_number": "string"
}

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "invite_status": "string",
  • "label": "string",
  • "name": "string",
  • "phone_number": "string"
}

Remove Tester

Remove a tester from an agent.

This endpoint removes a test device registration from the specified agent.

Query Parameters:

  • agent_id: Required. The agent ID.

Returns:

  • 204 No Content: Tester removed successfully
  • 404 Not Found: Tester not found
  • 401 Unauthorized: Invalid authentication
  • 502 Bad Gateway: the messaging platform returned an error (UPSTREAM_ERROR)
path Parameters
phone_number
required
string (Phone Number)
query Parameters
agent_id
required
string (Agent Id)

Agent ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "code": "VALIDATION_ERROR",
  • "details": {
    },
  • "message": "Request validation failed"
}

Get Tester

Get a specific tester by phone number.

Query Parameters:

  • agent_id: Required. The agent ID.

Returns:

  • 200 OK: Tester information
  • 404 Not Found: Tester not found
  • 401 Unauthorized: Invalid authentication
  • 502 Bad Gateway: the messaging platform returned an error (UPSTREAM_ERROR)
path Parameters
phone_number
required
string (Phone Number)
query Parameters
agent_id
required
string (Agent Id)

Agent ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "invite_status": "string",
  • "label": "string",
  • "name": "string",
  • "phone_number": "string"
}

Update Tester

Update a tester's Spirius-specific fields.

This endpoint updates only the label field. All other fields are kept up to date automatically.

Query Parameters:

  • agent_id: Required. The agent ID.

Request Body:

  • label: Updated label (can be null to clear, max 25 chars)

Returns:

  • 200 OK: Tester updated successfully
  • 404 Not Found: Tester not found
  • 401 Unauthorized: Invalid authentication
  • 502 Bad Gateway: the messaging platform returned an error (UPSTREAM_ERROR)
path Parameters
phone_number
required
string (Phone Number)
query Parameters
agent_id
required
string (Agent Id)

Agent ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
Label (string) or Label (null) (Label)

Updated label for this tester (e.g., 'John iOS')

Any of
<= 25 characters
string (Label) <= 25 characters

Updated label for this tester (e.g., 'John iOS')

Responses

Request samples

Content type
application/json
{
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "invite_status": "string",
  • "label": "string",
  • "name": "string",
  • "phone_number": "string"
}

Webhook Management

List webhooks for an agent

List all webhook configurations for a specific agent.

**Multiple Webhooks Pattern:**
- An agent can have multiple webhook endpoints
- Events are broadcast to ALL enabled webhooks that match the event filter
- Use `enabled_events` to control which webhooks receive which events

**Use Cases:**
- Separate endpoints for different services (analytics, CRM, compliance)
- Testing webhooks alongside production webhooks
- Third-party integrations (e.g., Segment, Customer.io)
query Parameters
agent_id
required
string (Agent Id)
header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create webhook configuration

Register a new webhook to receive RCS events for a specific agent.

**Security:**
- Webhook secret is automatically generated server-side (64-char hex)
- Secret is returned in response - store it securely for HMAC verification
- HTTPS required in production environments

**Event Filtering:**
- Use `enabled_events` to subscribe to specific event types
- Default: `["*"]` receives all events (broadcast pattern)
- Multiple webhooks per agent supported - events broadcast to ALL matching webhooks

**Available Event Types:**
- `"*"` - All events (wildcard)

Inbound (user messages):
- `"rcs.in.text"` - User sent a text message
- `"rcs.in.file"` - User sent a file (image, video, document)
- `"rcs.in.suggested.reply"` - User clicked a reply suggestion button
- `"rcs.in.suggested.action"` - User clicked an action suggestion (URL, dial, location)
- `"rcs.in.typing"` - User is typing (one attempt, never redelivered)
- `"rcs.in.location"` - User shared a location

Outbound (message status):
- `"rcs.out.delivered"` - Message delivered to user's device
- `"rcs.out.read"` - User opened and read the message
- `"rcs.out.failed"` - Message failed to send
- `"sms.out.sent"` - Message fell back to SMS (SMS fallback is not yet enabled)

Subscription:
- `"rcs.sub.subscribed"` - User subscribed in their messaging app
- `"rcs.sub.unsubscribed"` - User unsubscribed (includes STOP words)

**Example Filters:**
- `["*"]` - Receive all events
- `["rcs.out.delivered", "rcs.out.failed"]` - Only delivery status
- `["rcs.sub.unsubscribed"]` - Only unsubscribe events
- `["rcs.in.text", "rcs.in.suggested.reply"]` - Only inbound messages
- `["rcs.out.delivered", "rcs.out.read"]` - Message engagement tracking

**Event Delivery:**
- Events are signed with HMAC-SHA256 using the webhook secret
- Set `is_enabled: false` to create in disabled state (optional, defaults to true)
- Add `description` for organizational purposes (optional)

**Constraints:**
- Maximum 5 webhooks per agent
- Cannot create duplicate (agent_id + webhook_url) combination
- Returns 409 Conflict if same URL already registered for agent
- Returns 400 Bad Request if webhook limit exceeded

**Verification:**
- Use `POST /v1/webhooks/{id}/test` to verify webhook is working
header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
agent_id
required
string (Agent Id) [ 1 .. 100 ] characters

Agent identifier for this webhook

webhook_url
required
string <uri> (Webhook Url) [ 1 .. 2083 ] characters

Webhook URL to receive events

Description (string) or Description (null) (Description)

Optional description for organizational purposes

Any of
<= 255 characters
string (Description) <= 255 characters

Optional description for organizational purposes

enabled_events
Array of strings (Enabled Events)
Default: ["*"]

Event types to receive. Use ['*'] for all events, or specify individual event types

is_enabled
boolean (Is Enabled)
Default: true

Whether webhook is enabled

Responses

Request samples

Content type
application/json
{
  • "agent_id": "string",
  • "description": "string",
  • "enabled_events": [
    ],
  • "is_enabled": true,
  • "webhook_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "agent_id": "spirius-notifications",
  • "created_at": "2024-01-15T10:30:00Z",
  • "delivery_status": "healthy",
  • "delivery_status_since": null,
  • "description": "Production webhook for all events",
  • "enabled_events": [
    ],
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_enabled": true,
  • "updated_at": "2024-01-15T10:30:00Z",
  • "webhook_secret": "whsec_a1b2c3d4e5f6...",
}

Delete webhook configuration

Permanently delete a webhook configuration.

**⚠️ Warning:**
- Deletion is permanent and cannot be undone
- All event delivery to this webhook will stop immediately
- Consider disabling instead (`is_enabled: false`) for temporary pause

**Alternative:** Use `PATCH /v1/webhooks/{id}` with `is_enabled: false` 
to temporarily disable without losing configuration.
path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "code": "VALIDATION_ERROR",
  • "details": {
    },
  • "message": "Request validation failed"
}

Get webhook configuration

Retrieve a specific webhook configuration by ID.

**Note:** Webhooks are agent-owned. Any authenticated client can view any webhook.
path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "agent_id": "spirius-notifications",
  • "created_at": "2024-01-15T10:30:00Z",
  • "delivery_status": "healthy",
  • "delivery_status_since": null,
  • "enabled_events": [
    ],
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_enabled": true,
  • "updated_at": "2024-01-15T10:30:00Z",
  • "webhook_secret": "whsec_a1b2c3...",
}

Update webhook configuration

Update webhook configuration (partial update).

Updatable fields:

  • webhook_url: Change webhook endpoint URL
  • is_enabled: Enable or disable webhook temporarily
  • enabled_events: Change event subscription
  • description: Update organizational description

Available Event Types for enabled_events:

  • "*" - All events (wildcard)

Inbound (user messages):

  • "rcs.in.text" - User sent a text message
  • "rcs.in.file" - User sent a file (image, video, document)
  • "rcs.in.suggested.reply" - User clicked a reply suggestion button
  • "rcs.in.suggested.action" - User clicked an action suggestion (URL, dial, location)
  • "rcs.in.typing" - User is typing (one attempt, never redelivered)
  • "rcs.in.location" - User shared a location

Outbound (message status):

  • "rcs.out.delivered" - Message delivered to user's device
  • "rcs.out.read" - User opened and read the message
  • "rcs.out.failed" - Message failed to send
  • "sms.out.sent" - Message fell back to SMS (SMS fallback is not yet enabled)

Subscription:

  • "rcs.sub.subscribed" - User subscribed in their messaging app
  • "rcs.sub.unsubscribed" - User unsubscribed (includes STOP words)

Immutable fields:

  • agent_id: Cannot be changed (delete and recreate instead)
  • webhook_secret: Cannot be updated (use regenerate-secret endpoint)

All fields are optional - only provide fields you want to update.

path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Request Body schema: application/json
required
Description (string) or Description (null) (Description)

Webhook description

Any of
<= 255 characters
string (Description) <= 255 characters

Webhook description

Array of Enabled Events (strings) or Enabled Events (null) (Enabled Events)

Event types to receive

Any of
Array
string
Is Enabled (boolean) or Is Enabled (null) (Is Enabled)

Whether webhook is enabled

Any of
boolean (Is Enabled)

Whether webhook is enabled

Webhook Url (string) or Webhook Url (null) (Webhook Url)

New webhook URL

Any of
[ 1 .. 2083 ] characters
string <uri> (Webhook Url) [ 1 .. 2083 ] characters

New webhook URL

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "enabled_events": [
    ],
  • "is_enabled": true,
  • "webhook_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "agent_id": "spirius-notifications",
  • "created_at": "2024-01-15T10:30:00Z",
  • "delivery_status": "healthy",
  • "delivery_status_since": null,
  • "enabled_events": [
    ],
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "is_enabled": false,
  • "updated_at": "2024-01-15T16:45:00Z",
  • "webhook_secret": "whsec_a1b2c3...",
}

Disable webhook

Disable a webhook to temporarily stop receiving events without deleting the configuration.

path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "delivery_status": "healthy",
  • "delivery_status_since": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "enabled_events": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "webhook_secret": "string",
  • "webhook_url": "string"
}

Enable webhook

Enable a webhook to resume receiving events.

path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "agent_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "delivery_status": "healthy",
  • "delivery_status_since": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "enabled_events": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_enabled": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "webhook_secret": "string",
  • "webhook_url": "string"
}

Regenerate webhook secret

Generate a new webhook secret (secret rotation).

**Use cases:**
- Secret compromised or exposed
- Periodic security policy (rotate every 90 days)
- Initial deployment mistake

**⚠️ Important:**
- Old secret is immediately invalidated
- Update your webhook verification code before events arrive
- Test webhook after regeneration to confirm new secret works

**Process:**
1. Call this endpoint to get new secret
2. Update your webhook handler to verify with new secret
3. Test webhook with `POST /v1/webhooks/{id}/test`
path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "regenerated_at": "2024-01-20T09:15:00Z",
  • "webhook_secret": "whsec_x7y8z9..."
}

Test webhook endpoint

Send a test event to the webhook URL to verify it's working correctly.

**What it does:**
- Sends a test event with `event_type: "webhook.test"`
- Measures response time
- Validates webhook endpoint is reachable

**Use cases:**
- Verify webhook after initial setup
- Test after URL change
- Confirm webhook after secret regeneration
- Troubleshoot delivery issues

**Test event format:**
```json
{
    "event_type": "webhook.test",
    "timestamp": "2024-01-15T10:30:00Z",
    "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "spirius-notifications",
    "message": "This is a test event from Spirius RCS API"
}
```

**Success criteria:**
- Webhook returns 200, 201, 202, or 204
- Response received within 10 seconds

A successful test counts as a delivery: a `failing` or `dead` webhook becomes `healthy` and its queued events are sent at once.
path Parameters
webhook_id
required
string <uuid> (Webhook Id)

Webhook ID

header Parameters
x-api-key
required
string (X-Api-Key)

API key for authentication

x-client-id
required
string (X-Client-Id)

Client ID for identification

Responses

Response samples

Content type
application/json
Example
{
  • "error_message": "HTTP 500: Internal Server Error",
  • "response_time_ms": 1234,
  • "status_code": 500,
  • "success": false,
  • "test_event_sent": {
    }
}