{ "openapi": "3.0.3", "info": { "title": "RubiConnect Messaging Platform & MCP Server", "description": "Model Context Protocol (MCP) server and programmatic interface for RubiConnect. Supports OAuth 2.1 with S256 PKCE, Dynamic Client Registration (RFC 7591), and granular least-privilege scopes (mcp:read for read-only workspace intelligence across 16 tools and mcp / mcp:write for full messaging, template, conversation flow, and campaign orchestration across all 26 tools).", "version": "1.1.0" }, "servers": [ { "url": "https://console.rubiconnect.com/api/v1", "description": "Production Server" } ], "paths": { "/messages/send": { "post": { "summary": "Send a single message or stream broadcast", "description": "Sends a plain text, media card, or rich template message to a recipient phone number, OR streams a zero-persistence bulk broadcast directly from a remote CSV/JSONL HTTPS URL.", "operationId": "sendMessage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "202": { "description": "Accepted and queued for transmission or streaming", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } } }, "400": { "description": "Bad request (invalid parameter validation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (feature disabled for this account tier, or insufficient_scope when using a read-only mcp:read OAuth token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent or template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": ["mcp", "mcp:write"] } ] } }, "/campaigns": { "post": { "summary": "Create and dispatch a campaign", "description": "Creates a new campaign and dispatches messages to stored contact lists or pre-signed remote CSV/JSONL URLs.", "operationId": "createCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "201": { "description": "Campaign created and queued for broadcast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden (feature disabled or insufficient_scope when using a read-only mcp:read OAuth token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": ["mcp", "mcp:write"] } ] }, "get": { "summary": "Query campaign status and stats", "description": "Fetches a single campaign by ID or lists recent campaigns with real-time delivery and read counters.", "operationId": "getCampaign", "parameters": [ { "name": "id", "in": "query", "description": "Specific campaign ID to query", "required": false, "schema": { "type": "string" } }, { "name": "agentId", "in": "query", "description": "Filter campaigns by agent ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCampaignResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": ["mcp:read", "mcp"] } ] } }, "/capabilities/check": { "post": { "summary": "Check RCS capability", "description": "Verifies whether a recipient phone number is capable of receiving rich RCS messages for a specific agent context.", "operationId": "checkCapability", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityCheckRequest" } } } }, "responses": { "200": { "description": "Capability check successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityCheckResponse" } } } }, "400": { "description": "Bad request (invalid parameter validation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": ["mcp:read", "mcp"] } ] } }, "/webhooks": { "post": { "summary": "Webhook event callback receiver", "description": "Endpoint implemented by the client to receive live notifications (message.status_updated and message.received) from RubiConnect.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MessageStatusUpdatedEvent" }, { "$ref": "#/components/schemas/MessageReceivedEvent" } ] } } } }, "responses": { "200": { "description": "Webhook event successfully processed" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "BearerAuth": { "type": "http", "scheme": "bearer" }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 Authorization Code flow with mandatory S256 PKCE. Supports RFC 7591 Dynamic Client Registration (/api/oauth/register) and RFC 7009 Token Revocation (/api/oauth/revoke).", "flows": { "authorizationCode": { "authorizationUrl": "https://console.rubiconnect.com/en/authorize", "tokenUrl": "https://console.rubiconnect.com/api/oauth/token", "scopes": { "mcp:read": "Read-only access to workspace agents, templates, conversation flows, campaigns, inbox transcripts, capability checks, and analytics (16 MCP tools).", "mcp:write": "Write access to dispatch messages, create/submit templates, build/clone/update/trigger conversation flows, and orchestrate campaigns.", "mcp": "Full read and write access to all 26 MCP tools and outbound messaging endpoints." } } } } }, "schemas": { "CapabilityCheckRequest": { "type": "object", "required": [ "recipient", "agentId" ], "properties": { "recipient": { "type": "string", "description": "Destination phone number in E.164 format.", "example": "+15555551234" }, "agentId": { "type": "string", "description": "The registered agent identifier.", "example": "marketing-agent" } } }, "CapabilityCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "recipient": { "type": "string", "description": "Normalized E.164 phone number.", "example": "+15555551234" }, "isRcs": { "type": "boolean", "description": "Whether the recipient is RCS-capable.", "example": true }, "status": { "type": "string", "description": "Detailed RCS capability status.", "example": "CAPABILITY_FULL" }, "features": { "type": "array", "items": { "type": "string" }, "description": "Supported features/capabilities of the handset.", "example": ["UP_2_0", "GEO_PUSH"] }, "optedOut": { "type": "boolean", "description": "Whether the recipient has opted out of communication.", "example": false } } }, "SendMessageRequest": { "type": "object", "required": [ "agentId" ], "properties": { "recipient": { "type": "string", "description": "Destination phone number in E.164 format. Required for single send if contactsUrl is not specified.", "example": "+15555551234" }, "contactsUrl": { "type": "string", "description": "Pre-signed HTTPS CSV or JSONL URL to stream contacts from with zero database persistence.", "example": "https://storage.googleapis.com/crm-exports/customers.csv" }, "urlFormat": { "type": "string", "enum": ["csv", "jsonl"], "description": "Format of contactsUrl file.", "default": "csv", "example": "csv" }, "agentId": { "type": "string", "description": "The registered agent identifier.", "example": "marketing-agent" }, "text": { "type": "string", "description": "Plain text message content. Mutually exclusive with mediaUrl and templateId.", "example": "Hello, thank you for your order!" }, "mediaUrl": { "type": "string", "description": "Public URL pointing to a media attachment. Mutually exclusive with text and templateId.", "example": "https://example.com/banner.jpg" }, "templateId": { "type": "string", "description": "The pre-configured rich template ID. Mutually exclusive with text and mediaUrl.", "example": "order_delivery_alert" }, "contentVariables": { "type": "object", "description": "Key-value pair map to interpolate variables inside messages or templates.", "additionalProperties": { "type": "string" }, "example": { "customerName": "Alice", "orderNumber": "RC-123" } }, "allowSmsFallback": { "type": "boolean", "description": "Whether to fallback to SMS if recipient handset lacks RCS capability.", "default": false, "example": true }, "callbackUrl": { "type": "string", "description": "Custom webhook URL to receive status callbacks specifically for this message.", "example": "https://callback.mycompany.com/webhook" } } }, "SendMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "messageId": { "type": "string", "description": "Unique message tracking identifier (for single send).", "example": "msg_9a8b7c6d5e4f3g2h1i" }, "broadcastId": { "type": "string", "description": "Unique broadcast campaign identifier (for remote URL streaming).", "example": "bcast_1725001234567_8901" }, "status": { "type": "string", "enum": [ "sending", "sent", "streaming" ], "example": "streaming" }, "channel": { "type": "string", "example": "RCS" } } }, "CreateCampaignRequest": { "type": "object", "required": [ "name", "agentId" ], "properties": { "name": { "type": "string", "description": "Campaign display name.", "example": "Summer VIP Alert" }, "agentId": { "type": "string", "description": "Registered agent ID.", "example": "marketing-agent" }, "templateId": { "type": "string", "description": "Pre-configured template ID to broadcast.", "example": "summer_vip_sale" }, "flowId": { "type": "string", "description": "Interactive flow ID to trigger for recipients.", "example": "flow_123" }, "recipientSource": { "type": "string", "enum": ["contacts", "remote_url"], "default": "contacts", "description": "Audience source for the campaign." }, "contactsUrl": { "type": "string", "description": "Pre-signed HTTPS CSV/JSONL URL (required when recipientSource is remote_url).", "example": "https://storage.googleapis.com/crm-exports/customers.csv" }, "urlFormat": { "type": "string", "enum": ["csv", "jsonl"], "default": "csv" }, "contactListName": { "type": "string", "description": "Contact list name (required when recipientSource is contacts)." }, "sendNow": { "type": "boolean", "default": true, "description": "Immediately trigger and stream the broadcast." }, "allowSmsFallback": { "type": "boolean", "default": false } } }, "CreateCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "campaignId": { "type": "string", "example": "camp_1725001234567_4321" }, "status": { "type": "string", "example": "Sending" }, "recipientSource": { "type": "string", "example": "remote_url" }, "contactsUrl": { "type": "string", "example": "https://storage.googleapis.com/crm-exports/customers.csv" } } }, "GetCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "stats": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "read": { "type": "integer" }, "failed": { "type": "integer" } } } } } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid or missing parameter: recipient is required." } } }, "MessageStatusUpdatedEvent": { "type": "object", "required": [ "eventId", "event", "timestamp", "data" ], "properties": { "eventId": { "type": "string", "description": "Unique event identifier.", "example": "evt_0a1b2c3d4e5f6g7h8i9j" }, "event": { "type": "string", "enum": [ "message.status_updated" ], "example": "message.status_updated" }, "timestamp": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the event was generated.", "example": "2026-06-10T14:21:04Z" }, "data": { "type": "object", "required": [ "messageId", "recipient", "status" ], "properties": { "messageId": { "type": "string", "description": "Unique message tracking identifier.", "example": "msg_9a8b7c6d5e4f3g2h1i" }, "recipient": { "type": "string", "description": "Handset phone number in E.164 format.", "example": "+15555551234" }, "status": { "type": "string", "enum": [ "Delivered", "Read", "Failed" ], "example": "Delivered" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-06-10T14:21:03Z" }, "readAt": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "error": { "type": "string", "nullable": true, "example": null } } } } }, "MessageReceivedEvent": { "type": "object", "required": [ "eventId", "event", "timestamp", "data" ], "properties": { "eventId": { "type": "string", "description": "Unique event identifier.", "example": "evt_0f9g8h7i6j5k4l3m2n1o" }, "event": { "type": "string", "enum": [ "message.received" ], "example": "message.received" }, "timestamp": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the event was generated.", "example": "2026-06-11T07:26:00Z" }, "data": { "type": "object", "required": [ "messageId", "sender", "content", "timestamp" ], "properties": { "messageId": { "type": "string", "description": "Unique received message identifier.", "example": "rcm_0a1b2c3d4e5f6g7h8i9j" }, "sender": { "type": "string", "description": "Sender handset phone number in E.164 format.", "example": "+15555551234" }, "content": { "type": "string", "nullable": true, "description": "Text content of the message.", "example": "Hello World" }, "timestamp": { "type": "string", "format": "date-time", "description": "The ISO 8601 timestamp when the message was received by the system.", "example": "2026-06-11T07:26:00Z" }, "suggestionResponse": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "description": "Button label text." }, "postbackData": { "type": "string", "description": "Postback data payload associated with the button action." } }, "example": null }, "mediaUrl": { "type": "string", "nullable": true, "description": "URL of the media attachment shared by the contact.", "example": null }, "location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number", "example": 48.8584 }, "longitude": { "type": "number", "example": 2.2945 }, "label": { "type": "string", "nullable": true, "example": "Eiffel Tower" } }, "example": null } } } } } } } }