# SendRCS API > SendRCS API for sending rich, interactive messages via RCS (Rich Communication Services) with SMS fallback. Complete documentation in one file, with every endpoint, schema and webhook payload: https://docs.sendrcs.eu/llms-full.txt Machine-readable specification: https://docs.sendrcs.eu/openapi.yaml ## Quick Start Base URL: `https://api.sendrcs.eu/api/rcs` Authentication: Bearer token or API key in `X-API-Key` header (not needed for the sandbox endpoints below). ## Try it without an account (Sandbox) You can validate and preview any message body before you have an API key. The sandbox runs the same validator as `POST /send`, returns the same error shape, and gives you a phone-mockup preview link. Nothing is sent, no credits are used, and no auth header is needed. - `POST https://api.sendrcs.eu/api/rcs/sandbox/validate` - validation only - `POST https://api.sendrcs.eu/api/rcs/sandbox/preview` - validation plus a `share_url` (expires after 24 hours) - `GET https://api.sendrcs.eu/api/rcs/sandbox/samples` - sample images, a video and a PDF you may reference Content rule worth knowing before you start: an email address or a web address (URL, www. host or bare domain such as example.com) in the `text` of a text or textBasic message returns a validation warning (the message is still accepted), because iPhones reject such messages while Android delivers them. To reach every phone put links on chips and buttons, or use a rich card; card titles, descriptions and chip labels may contain an address. Send the exact body you would send to `/send` or `/send-batch`. Recipient and sender fields (`phoneNumber`, `sendernameId`, `scheduleAt`, ...) are accepted and listed under `sandbox.ignored_fields`. Only media from `/sandbox/samples` is rendered; other `https` URLs still pass validation but show as a placeholder in the preview. ```bash curl -X POST https://api.sendrcs.eu/api/rcs/sandbox/preview \ -H "Content-Type: application/json" \ -d '{ "messageType": "richCard", "content": { "title": "Your order is on its way", "description": "Track the parcel or talk to us.", "media": { "height": "TALL", "contentDescription": "Pair of white running shoes on a wooden floor", "contentInfo": { "fileUrl": "https://sendrcs.eu/images/rcsexamples/shoes-1.jpg", "contentType": "image/jpeg" } }, "cardActions": [ { "type": "openUrl", "text": "Track order", "openUrlAction": { "url": "https://example.com/track" } }, { "type": "dial", "text": "Call us", "dialAction": { "phoneNumber": "+4512345678" } } ] } }' ``` Read `valid`, `errors`, `warnings`, `preview.share_url` and `preview.expires_at`. Open `share_url` to see the message on a phone mockup (Android and iOS). Rate limit: 20 requests per minute and 100 per day per IP. Sandbox preview ids cannot be used to send. When you are ready, create a free account at https://app.sendrcs.eu/auth/signup and call `/send` with your API key. ## Core Endpoints ### Send Single Message POST /api/rcs/send Send an RCS message to one recipient. Supports text, rich cards, carousels, and media with interactive buttons. ### Send Batch Messages POST /api/rcs/send-batch Send to up to 10,000 recipients. Automatic disabled contact filtering and progress tracking. ### Send Standalone SMS POST /api/rcs/send-sms Send a plain SMS (no RCS involved). Max 1530 characters, billed per segment. Supports the full merge field set (see Available Merge Fields) including `{{unsubscribe_link}}` - placeholders are replaced per recipient before segments are calculated. Supports `scheduleAt`/`timeZone` scheduling. When a Shopify store is connected, links to that store are replaced by short tracked links at send time (clicks and purchases show up in statistics); the billed segment count reflects the final text. ### Cancel a Scheduled Message DELETE /api/messages/{id} Cancel one scheduled message before it is sent, RCS or SMS alike. Only messages still in `SCHEDULED` status can be cancelled; anything already sending or sent returns `404`. Pass the `messageId` returned by a scheduled `/send` or `/send-sms`, or an `id` from `GET /api/messages/log?status=SCHEDULED`. Cancelling one recipient of a scheduled batch drops only that message and leaves the rest of the batch on schedule - to cancel a whole batch use `DELETE /api/rcs/batch/{jobId}` instead. Requires the `messages:write` permission. ### List Interactions (button clicks and replies) GET /api/messages/interactions Every button tap and typed reply on the messages you sent, newest first, with the same date window (default 7 days, max 31) and cursor paging as `/api/messages/log`. Each row carries `messageId`, the sent message the button belonged to, plus `buttonText`, `postbackData`, `buttonType` (`reply` or `action`), `actionType`, `campaignName`, `sendId` and `phoneNumber`. Filter by `messageId` (one message, no date range needed), `campaignName`, `phoneNumber` or `interactionType` (`button_click` / `reply_received`). Tracked store links log a postback and a redirect per tap; the redirect row has `trackedLinkDuplicate: true`. Join a row to `GET /api/messages/log?messageId=` or `GET /api/messages/{id}/content` to see the exact card or chips. Requires the `messages:read` permission. ## Message Types - **text**: Text with up to 11 chip suggestions (reply buttons) - **textBasic**: Plain text only (no interactive elements) - **richCard**: Card with image, title, description, and up to 4 action buttons + 4 chip suggestions - **carousel**: Up to 10 rich cards in horizontal scroll - **media**: Standalone image or video with optional suggestions - **file**: Send files (PDF, documents, etc.) - **image**: Send images (JPG, PNG, GIF, etc.) - **video**: Send videos (MP4, etc.) - **audio**: Send audio files (MP3, etc.) ## Key Features - **Interactive Buttons**: Chip suggestions (11 max) and card actions (3 max per card) - **SMS Fallback**: Automatic fallback when RCS unavailable - **Scheduling**: Timezone-aware scheduling with `scheduleAt` and `timeZone` - **skipContactCreation**: Send without creating contact records - **Conversation Billing**: 24-hour conversation windows for cost optimization ## Example: Send Text with Buttons ```json POST /api/rcs/send { "phoneNumber": "+4512345678", "messageType": "text", "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1", "content": { "text": "Hello! How can we help?", "suggestions": [ { "reply": { "text": "Book Appointment", "postbackData": "book", "webhookUrl": "https://yourapp.com/webhook" } }, { "action": { "text": "Call Us", "type": "dial", "dialAction": { "phoneNumber": "+4512345678" } } } ] } } ``` ## Example: Rich Card with Actions ```json { "phoneNumber": "+4512345678", "messageType": "richCard", "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1", "content": { "title": "Special Offer", "description": "50% off today!", "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://example.com/offer.jpg" } }, "cardActions": [ { "text": "Shop Now", "type": "openUrl", "openUrlAction": { "url": "https://shop.example.com" } }, { "text": "Details", "type": "postback", "postbackData": "details", "webhookUrl": "https://yourapp.com/webhook" } ] }, "smsFallback": { "message": "50% off! Visit shop.example.com", "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e2" } } ``` ## Example: Send File/Image/Video/Audio ```json { "phoneNumber": "+4512345678", "messageType": "file", "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1", "content": { "media": { "contentInfo": { "fileUrl": "https://example.com/document.pdf" } } } } ``` Use `messageType`: `file`, `image`, `video`, or `audio` depending on the content type. ## Limits - Max chip suggestions: 11 (any message type, any mix of reply and action chips) - Max card actions: 4 per card - Max carousel cards: 10 - Max batch recipients: 10,000 - Max text length: 3,072 characters - Max button text: 25 characters - Max SMS fallback: 1,530 characters ## Action Types for Card Buttons (cardActions) - `openUrl` - Open URL in browser - `openUrlInWebview` - Open URL in in-app webview (`viewMode`: FULL, TALL, or HALF) - `dial` - Open phone dialer - `postback` - Send postback data to webhook (card-only; on chips use a `reply` with postbackData) - `addToCalendar` - Add to calendar via `calendarAction` (card-only; chips use `createCalendarEvent`) - `viewLocation` - Open maps - `shareLocation` - Share location - `unsubscribeLink` - Open per-recipient unsubscribe URL (`{{unsubscribe_link}}`) ## Action Types for Chips - `reply` - Send a text reply with postbackData to webhook - `dial` - Open phone dialer - `openUrl` - Open URL - `openUrlInWebview` - Open URL in in-app webview (`viewMode`: FULL, TALL, or HALF) - `createCalendarEvent` - Add to calendar via `createCalendarEventAction` (chip-only; card buttons use `addToCalendar`) - `viewLocation` - Open maps - `shareLocation` - Share location - `unsubscribeLink` - Open per-recipient unsubscribe URL (`{{unsubscribe_link}}`) - `unsubscribe` - Send stop keyword as reply to trigger unsubscribe flow (chip-only, uses `unsubscribeAction: { stopKeyword: "STOP" }`). The stopKeyword is auto-corrected at preview time to match the active trigger configuration for the sendername. ## Open in Webview (keep the recipient in the chat) `openUrlInWebview` opens the page inside the messaging app instead of the external browser. `viewMode` is `FULL` (full screen), `TALL` or `HALF` (sheet over the conversation). It works the same on card buttons and chips: ```json { "messageType": "richCard", "sendernameId": "60f1b2c3d4e5f6a7b8c9d0e1", "content": { "title": "New arrivals", "description": "Browse the collection without leaving the chat.", "media": { "height": "TALL", "contentInfo": { "fileUrl": "https://example.com/new.jpg" } }, "cardActions": [ { "text": "Shop now", "type": "openUrlInWebview", "openUrlInWebviewAction": { "url": "https://shop.example.com/new", "viewMode": "FULL" }, "postbackData": "shop_now", "webhookUrl": "https://yourapp.com/webhook" } ], "suggestions": [ { "action": { "text": "Size guide", "type": "openUrlInWebview", "openUrlInWebviewAction": { "url": "https://shop.example.com/size-guide", "viewMode": "FULL" } } } ] } } ``` ## Webhooks Your webhook URL receives button clicks: ```json { "event": "button_interaction", "interaction": { "type": "button_click", "buttonText": "Book Appointment", "postbackData": "book_appointment" }, "contact": { "phone": "+4512345678", "name": "John Doe" } } ``` ### Form submission webhooks Configure one webhook per form in Settings > Webhooks (Form Submission Webhooks tab). The webhook receives two events: - `form_submission` — fired on every form submit, before opt-in confirmation. `optIn.status` is `PENDING`; `data` contains the submitted values (custom fields include labels); `optIn.confirmationSent` is `false` when the "submit once" throttle suppressed a repeat opt-in message. - `form_optin_confirmed` — fired once when the visitor confirms the double opt-in. `optIn.status` is `CONFIRMED`; the contact is now active and (when `optIn.dataApplied` is true) the submitted data and groups have been written to it. ```json { "event": "form_submission", "form": { "id": "...", "name": "Newsletter signup", "slug": "..." }, "submission": { "action": "created", "submittedAt": "2024-01-15T10:30:00Z" }, "optIn": { "status": "PENDING", "confirmationSent": true, "confirmedAt": null }, "contact": { "id": "...", "phone": "+4512345678", "optInStatus": "PENDING" }, "data": { "phone": "+4512345678", "firstName": "John", "email": "john@example.com", "customFields": [{ "id": "...", "label": "Company", "value": "Acme Inc" }] } } ``` ## Contacts API Base URL: `https://api.sendrcs.eu/api/v1/contacts` Requires `contacts:read` / `contacts:write` and `custom-fields:read` / `custom-fields:write` API key permissions. ### Contact CRUD - **GET /api/v1/contacts** — List contacts with cursor pagination, search (`?search=`), phone lookup (`?phone=`), filters (`?disabled=`, `?group=`), and optional custom fields (`?include=customFields`) - **GET /api/v1/contacts/count** — Get contact count with optional filters - **GET /api/v1/contacts/:id** — Get single contact - **POST /api/v1/contacts** — Create contact (phone required, must be unique) - **PUT /api/v1/contacts/:id** — Update contact (partial updates) - **DELETE /api/v1/contacts/:id** — Delete contact and all associated data ### Bulk Operations - **POST /api/v1/contacts/bulk** — Bulk create/upsert up to 1,000 contacts. Set `upsert: true` to update existing by phone. - **PATCH /api/v1/contacts/bulk/disable** — Soft-delete multiple contacts - **PATCH /api/v1/contacts/bulk/enable** — Re-enable disabled contacts ### Custom Field Definitions - **GET /api/v1/contacts/fields** — List all custom merge field definitions - **POST /api/v1/contacts/fields** — Create custom field (name + tag, tag used as `{{tag}}` in messages) - **GET /api/v1/contacts/fields/:fieldId** — Get single field definition - **PUT /api/v1/contacts/fields/:fieldId** — Update field definition - **DELETE /api/v1/contacts/fields/:fieldId** — Delete field (`?force=true` to delete even if in use) ### Per-Contact Custom Field Values - **GET /api/v1/contacts/:id/fields** — Get all custom field values for a contact - **PUT /api/v1/contacts/:id/fields** — Bulk set values (by fieldId or tag) - **PUT /api/v1/contacts/:id/fields/:fieldId** — Set single value - **DELETE /api/v1/contacts/:id/fields/:fieldId** — Delete value ### Example: Create Contact with Custom Fields ```json POST /api/v1/contacts { "firstName": "Peter", "lastName": "Thomsen", "phone": "4512345678", "email": "peter@example.com", "groups": ["60f1b2c3d4e5f6a7b8c9d0e1"], "customFields": [ { "fieldId": "665ghi789jkl012mno345pqr", "value": "Premium" } ] } ``` ### Example: Bulk Upsert ```json POST /api/v1/contacts/bulk { "contacts": [ { "phone": "4512345678", "firstName": "Peter", "customFields": [{ "tag": "customer_status", "value": "Gold" }] }, { "phone": "4587654321", "firstName": "Anna" } ], "upsert": true, "groups": ["60f1b2c3d4e5f6a7b8c9d0e1"] } ``` ## Groups API Base URL: `https://api.sendrcs.eu/api/v1/groups` Requires `groups:read` / `groups:write` API key permissions. ### Group CRUD - **GET /api/v1/groups** — List all groups with contact counts, sorted by newest first - **GET /api/v1/groups/:id** — Get single group. Add `?includeContacts=true&limit=50&offset=0` for paginated contact list - **POST /api/v1/groups** — Create group (name required, optional description) - **PUT /api/v1/groups/:id** — Update group name and/or description - **DELETE /api/v1/groups/:id** — Delete group (does NOT delete contacts, only removes group references) ### Group Membership - **POST /api/v1/groups/:id/contacts** — Add contacts to a group. Linked campaigns and flows are updated automatically. Duplicates silently ignored. - **DELETE /api/v1/groups/:id/contacts** — Remove contacts from a group. Linked campaigns and flows are updated automatically. Contacts NOT deleted. Both membership endpoints accept `{ "contactIds": ["id1", "id2", ...] }` (up to 10,000 IDs). ### Example: Create Group and Add Contacts ```json POST /api/v1/groups { "name": "VIP Customers", "description": "High-value customers" } ``` ```json POST /api/v1/groups/60f1b2c3d4e5f6a7b8c9d0e1/contacts { "contactIds": ["665abc123def456ghi789jkl", "665abc123def456ghi789jkm"] } ``` ## Templates API Base URL: `https://api.sendrcs.eu/api/v1/templates` Requires `templates:read` / `templates:write` API key permissions. ### Template CRUD - **GET /api/v1/templates** — List templates with pagination. Filters: `?type=` (SMS/RCS), `?rcsMessageType=`, `?templateGroupId=` (a template group id, or `none` for ungrouped), `?context=` (event/flow/general), `?search=`. Pagination: `?page=1&limit=20`. Sort: `?sort=name&order=asc` - **GET /api/v1/templates/:id** — Get single template. RCS templates include `parsedContent` with structured message data - **POST /api/v1/templates** — Create template. For RCS: pass content as object + rcsMessageType. For SMS: content as string. Optional `templateGroupId` places it in a template group (folder) - **PUT /api/v1/templates/:id** — Update template (partial update). RCS content re-wrapped if rcsMessageType changes - **DELETE /api/v1/templates/:id** — Delete template permanently ### Template Groups Template groups are folders for organizing message templates. They are NOT contact groups. Each template belongs to at most one template group. - **GET /api/v1/templates/groups** — List all template groups with `templateCount` each, plus `ungroupedTemplateCount` - **POST /api/v1/templates/groups** — Create a template group (`name` required, unique per account, max 100 chars) - **PUT /api/v1/templates/groups/:id** — Rename a template group - **DELETE /api/v1/templates/groups/:id** — Delete a template group. Its templates are NOT deleted, they become ungrouped - **POST /api/v1/templates/groups/assign** — Move templates into a group: `{ "templateIds": [...], "templateGroupId": "..." }`. Pass `"templateGroupId": null` to ungroup ### Example: Create SMS Template ```json POST /api/v1/templates { "name": "Welcome SMS", "type": "SMS", "content": "Welcome {{contact_first_name}}! Thanks for signing up.", "context": "general" } ``` ### Example: Create RCS Template ```json POST /api/v1/templates { "name": "Product Card", "type": "RCS", "rcsMessageType": "richCard", "content": { "title": "New Product Available", "description": "Check out our latest product!", "media": { "height": "TALL", "contentInfo": { "fileUrl": "https://example.com/image.jpg" } }, "cardActions": [ { "text": "View Product", "type": "openUrl", "openUrlAction": { "url": "https://example.com/product" } } ] }, "templateGroupId": "665ghi789jkl012mno345abc" } ``` ## MCP Tools for Contacts, Groups & Templates The SendRCS MCP server (at `https://api.sendrcs.eu/api/mcp`) also exposes contact, group, custom field, and template management as MCP tools. These can be used by AI assistants via the Model Context Protocol. ### Contact Tools (MCP) - **list_contacts** — List with cursor pagination, search, phone lookup, filters (disabled, group), sorting, optional custom fields - **count_contacts** — Count with optional filters (disabled, group, search) - **get_contact** — Get single contact by ID with groups and custom field values - **create_contact** — Create contact (phone required, unique). Can assign groups and custom fields - **update_contact** — Partial update (name, phone, email, disabled, groups, custom fields) - **delete_contact** — Hard delete with cascading cleanup (messages, flows, events, groups, fields) - **bulk_create_contacts** — Create/upsert up to 1,000 contacts with groups and custom fields - **bulk_disable_contacts** — Soft-disable contacts, cancels scheduled messages and flow enrollments - **bulk_enable_contacts** — Re-enable disabled contacts ### Group Tools (MCP) - **list_groups** — List all groups with contact counts - **get_group** — Get group by ID, optionally with paginated contact list - **create_group** — Create group (name required, optional description) - **update_group** — Update group name/description - **delete_group** — Delete group (does NOT delete contacts, only removes group references) - **add_contacts_to_group** — Add contacts to a group; linked campaigns and flows are updated automatically - **remove_contacts_from_group** — Remove contacts from a group; linked campaigns and flows are updated automatically ### Custom Field Tools (MCP) - **list_custom_fields** — List all custom merge field definitions (tags become `{{tag}}` placeholders) - **create_custom_field** — Create field definition (name + tag, tag must be unique) - **delete_custom_field** — Delete field definition (requires `force: true` if in use) - **set_contact_custom_fields** — Set or delete values on a contact (by fieldId or tag, null to delete) ### Template Tools (MCP) - **list_templates** — List templates with pagination, filtering by type (SMS/RCS), rcsMessageType, template group, context, and name search - **get_template** — Get single template by ID. RCS templates include parsed content in rcs_send format - **create_template** — Create template. For RCS: pass content as an object (same format as rcs_send), the tool handles storage - **update_template** — Partial update of template fields (name, content, template group, etc.) - **delete_template** — Delete a template permanently ### Template Group Tools (MCP) Template groups are folders for message templates, NOT contact groups. - **list_template_groups** — List all template groups with template counts, plus the count of ungrouped templates - **create_template_group** — Create a template group (name required, unique per account) - **update_template_group** — Rename a template group - **delete_template_group** — Delete a template group. Templates inside are NOT deleted, they become ungrouped - **assign_templates_to_template_group** — Move templates into a group, or pass `templateGroupId: null` to ungroup them ### Template-based Preview (MCP) The `rcs_preview` tool accepts an optional `templateId` parameter. When provided, the template's stored content and messageType are loaded automatically — no need to pass content or messageType separately. Only `sendernameId` is required alongside `templateId`. ## Available Merge Fields ### System merge fields (always available) - `{{contact_first_name}}`, `{{contact_last_name}}`, `{{contact_phone}}`, `{{contact_email}}` - `{{today}}` - `{{company_name}}`, `{{company_email}}`, `{{company_phone}}`, `{{company_website}}` - `{{company_address}}`, `{{company_city}}`, `{{company_country}}` - `{{contact_person}}`, `{{business_first_name}}`, `{{business_last_name}}` - `{{gdpr_email}}`, `{{gdpr_phone}}` - `{{unsubscribe_link}}` ### Custom merge fields Use the tag from your custom field definitions: `{{customer_status}}`, `{{loyalty_points}}`, etc. ## Full Documentation - OpenAPI Spec: /openapi.yaml - AI Instructions: /ai-instructions/