RCS API (BETA) (1.0.0)

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

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 critical dependencies:

• Redis connection
• PostgreSQL connection

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

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.
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
Subscription	rcs.sub.subscribed	User subscribed via Google Messages UI or other channels	User explicitly consents
Subscription	rcs.sub.unsubscribed	User unsubscribed via Google Messages UI, 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-299	Any 2xx status code acknowledges receipt
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	RBM 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

Retry Behavior

Scenario	Behavior
Successful Delivery (2xx response)	No retries - event acknowledged
Failed Delivery (non-2xx, timeout, connection error)	Automatic retry with exponential backoff
Retry Schedule	Exponential backoff over several minutes
Maximum Attempts	Multiple attempts before dead-letter queue
Duplicate Detection	Same event may be delivered multiple times - use event_id to detect duplicates

Implementation Best Practices

1. Respond immediately - Return HTTP 200-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 HMAC-SHA256 hash of the 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)
    if signature and 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/..."
    }
  }
}

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"
}

User Subscribed Event (Google Messages UI)

{
  "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 (Google Messages UI)

{
  "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"
}

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

This endpoint requires X-API-Key header authentication. It validates the request, publishes the message to a queue for async processing, and returns immediately. The actual RBM API call happens asynchronously in the worker service.

Async Processing:

• Message is queued and processed asynchronously by the message worker
• API returns immediately (< 50ms) with a message_id
• Actual delivery happens within seconds via the worker

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

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: Google API error

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:

• 200 OK: Tester created successfully
• 400 Bad Request: Invalid request
• 401 Unauthorized: Invalid authentication
• 409 Conflict: Tester already exists
• 502 Bad Gateway: Google API error

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: Google API error

Update a tester's Spirius-specific fields.

This endpoint updates only the label field. All RBM fields are synced automatically from Google's API to ensure consistency.

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: Google API error

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: Google API error

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

**Caching Strategy:**
- Results are cached globally (shared across all clients)
- 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.

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)

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

Subscription:
- `"rcs.sub.subscribed"` - User subscribed via Google Messages
- `"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

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)

Retrieve a specific webhook configuration by ID.

**Note:** Webhooks are agent-owned. Any authenticated client can view any webhook.

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)
- `"message.sent"` - User sent a message or clicked a button
- `"message.delivered"` - Message delivered to device
- `"message.read"` - User read the message
- `"message.failed"` - Message failed to send
- `"user.typing"` - User is typing
- `"user.subscribed"` - User subscribed via Google Messages
- `"user.unsubscribed"` - User unsubscribed via Google Messages
- `"user.opted_in"` - User opted in via API/other channels
- `"user.opted_out"` - User opted out via API/other channels

**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.

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.

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`

Enable a webhook to resume receiving events.

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

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