RCS-Box API

Multi-Tenant API Gateway for Google RCS Business Messaging. Send text messages via your brand's agents, list your agents, and receive user-message callbacks — all through a single, authenticated API.

Base URL

All API requests are made to the following base URL:

All endpoints use JSON for request and response bodies.

Authentication

All /v1/* endpoints require an API key. Each tenant receives a unique 64-character hex key. You can authenticate using either method:

Option 1: Authorization Header (recommended)

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents

Option 2: X-API-Key Header

curl -H "X-API-Key: $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents

Endpoints

Public health check endpoint. Use this to verify the API is running.

Response

{
  "status": "ok",
  "timestamp": "2026-03-26T12:00:00Z"
}

Authenticated health check. Verifies both API availability and API key validity.

Response

{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-03-26T12:00:00Z"
}

Returns all RCS agents belonging to your tenant's brand. Only agents associated with your brand are visible.

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents

Response

{
  "agents": [
    {
      "id": 1,
      "tenant_id": 1,
      "google_agent_id": "brands/acme-corp/agents/my-agent",
      "brand_id": "acme-corp",
      "name": "ACME Support Bot",
      "display_name": "ACME Support Bot",
      "description": "ACME customer support agent for order questions.",
      "status": "LAUNCHED",
      "hosting_region": "EUROPE",
      "billing_category": "CONVERSATIONAL",
      "use_case": "PROMOTIONAL",
      "synced_at": "2026-03-25T10:30:00Z",
      "created_at": "2026-01-20T14:00:00Z",
      "updated_at": "2026-03-25T10:30:00Z"
    }
  ]
}

Agent Statuses

Returns details for a specific agent. The agent must belong to your tenant.

Path Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://rcs-box.example.com/v1/agents/1

Response

{
  "agent": {
    "id": 1,
    "tenant_id": 1,
    "google_agent_id": "brands/acme-corp/agents/my-agent",
    "brand_id": "acme-corp",
    "name": "ACME Support Bot",
    "display_name": "ACME Support Bot",
    "description": "ACME customer support agent for order questions.",
    "status": "LAUNCHED",
    "hosting_region": "EUROPE",
    "billing_category": "CONVERSATIONAL",
    "use_case": "PROMOTIONAL",
    "synced_at": "2026-03-25T10:30:00Z",
    "created_at": "2026-01-20T14:00:00Z",
    "updated_at": "2026-03-25T10:30:00Z"
  }
}

Error Response (404)

{
  "error": "Not Found",
  "message": "Agent not found"
}

Create a new RCS agent under your tenant's brand. The agent starts in DRAFT status and must be launched by an administrator before it can send messages.

Request Body

Example Request

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "display_name": "ACME Support Bot",
       "description": "ACME customer support agent for order questions.",
       "logo_uri": "https://acme.example.com/logo-224.png",
       "hero_uri": "https://acme.example.com/hero-1440x448.png",
       "color": "#1DA1F2",
       "privacy_uri": "https://acme.example.com/privacy",
       "terms_uri": "https://acme.example.com/terms",
       "phones": [{"number": "+4922199999701", "label": "Hotline"}],
       "emails": [{"address": "support@acme.example.com"}],
       "websites": [{"uri": "https://acme.example.com", "label": "Webseite"}],
       "hosting_region": "EUROPE",
       "billing_category": "CONVERSATIONAL",
       "use_case": "PROMOTIONAL"
     }' \
     https://api.box.rcs.jetzt/v1/agents

Smoke testing without real brand assets

For pure end-to-end smoke tests, dummyimage.com returns a real PNG at the exact dimensions and is publicly reachable by Google. Use it only for throwaway test agents — do not ship to production with placeholder images, because end-user phones will cache them.

"logo_uri": "https://dummyimage.com/224x224/1da1f2/ffffff.png",
"hero_uri": "https://dummyimage.com/1440x448/1da1f2/ffffff.png"

Error Response (422 — local validation)

When required fields are missing or invalid, you get a field-keyed hash of stable error codes before any call to Google. Codes are language-neutral so you can map them to your own UX:

{
  "error": "Validation failed",
  "errors": {
    "description": "missing",
    "hero_uri": "missing",
    "color": "invalid_format"
  }
}

Possible codes: missing, too_long, invalid_format, invalid_value, too_many (contact lists over 3 entries). A request without any contact method fails with {"errors": {"contacts": "missing"}}.

Error Response (422 — Google rejected payload)

If local validation passes but Google rejects the request (e.g. an image URL it can't fetch, a permission problem, or a constraint it enforces server-side), the upstream message is forwarded:

{
  "error": "Google API Error",
  "message": "Unexpected response: 400 - The supplied file URL https://example.com/logo.png is invalid, status: URL_ERROR"
}

Response (201)

{
  "agent": {
    "id": 7,
    "tenant_id": 1,
    "google_agent_id": "brands/acme-corp/agents/support-bot-xyz",
    "brand_id": "acme-corp",
    "name": "ACME Support Bot",
    "display_name": "ACME Support Bot",
    "description": "ACME customer support agent for order questions.",
    "status": "DRAFT",
    "hosting_region": "EUROPE",
    "billing_category": "CONVERSATIONAL",
    "use_case": "PROMOTIONAL",
    "synced_at": "2026-04-20T09:00:00Z",
    "created_at": "2026-04-20T09:00:00Z",
    "updated_at": "2026-04-20T09:00:00Z"
  }
}

Send any RCS message type via a specific agent — text, rich card, carousel, file, or text with interactive suggestions. The agent must belong to your tenant.

Request Body

The content_message shape mirrors Google's RCS Business Messaging AgentContentMessage — see the sub-sections below for each supported type.

Response (201)

{
  "message": {
    "id": 42,
    "tenant_id": 3,
    "agent_id": 7,
    "google_message_id": "phones/+491701234567/agentMessages/msg-abc-123",
    "phone": "+491701234567",
    "status": "SENT",
    "message_type": "text",
    "content": { "text": "Hello!" },
    "direction": "outbound",
    "sent_at": "2026-04-24T12:00:00Z",
    "delivered_at": null,
    "error_message": null,
    "created_at": "2026-04-24T12:00:00Z",
    "updated_at": "2026-04-24T12:00:00Z"
  }
}

message_type is one of text, rich_card, carousel, file.

Text message

The simplest message type. Max 3072 characters.

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "text": "Hallo! Willkommen bei ACME."
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

Text with suggestions

Suggestions are interactive chips shown below the message. You can mix any of the four action types per message — up to 11 suggestions total.

Suggestion types

• reply — tapping sends a reply back (you receive postbackData via webhook)
• action.openUrlAction — opens an external URL
• action.dialAction — starts a phone call
• action.viewLocationAction — opens a location on a map

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "text": "Wie können wir helfen?",
         "suggestions": [
           {
             "reply": {
               "text": "Bestellung verfolgen",
               "postbackData": "track_order"
             }
           },
           {
             "action": {
               "text": "Website öffnen",
               "postbackData": "open_site",
               "openUrlAction": { "url": "https://acme.example.com" }
             }
           },
           {
             "action": {
               "text": "Hotline anrufen",
               "postbackData": "call_hotline",
               "dialAction": { "phoneNumber": "+498000000000" }
             }
           },
           {
             "action": {
               "text": "Filiale auf Karte",
               "postbackData": "show_store",
               "viewLocationAction": {
                 "latLong": { "latitude": 50.9413, "longitude": 6.9583 },
                 "label": "ACME Köln"
               }
             }
           }
         ]
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

Standalone Rich Card

A card with title, description, media and up to 4 actions. Use cardOrientation: VERTICAL for full-width media at the top, HORIZONTAL for side-by-side. Media height: SHORT, MEDIUM, or TALL.

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "richCard": {
           "standaloneCard": {
             "cardOrientation": "VERTICAL",
             "cardContent": {
               "title": "Neuer Hoodie 🔥",
               "description": "Limited Edition — jetzt im Shop.",
               "media": {
                 "height": "MEDIUM",
                 "contentInfo": {
                   "fileUrl": "https://cdn.example.com/hoodie.jpg",
                   "thumbnailUrl": "https://cdn.example.com/hoodie-thumb.jpg"
                 }
               },
               "suggestions": [
                 {
                   "action": {
                     "text": "Jetzt kaufen",
                     "postbackData": "buy_hoodie",
                     "openUrlAction": { "url": "https://shop.example.com/hoodie" }
                   }
                 },
                 {
                   "reply": { "text": "Mehr Infos", "postbackData": "info_hoodie" }
                 }
               ]
             }
           }
         }
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

Carousel

Between 2 and 10 cards arranged horizontally. Users swipe through them. cardWidth: SMALL or MEDIUM.

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "richCard": {
           "carouselCard": {
             "cardWidth": "MEDIUM",
             "cardContents": [
               {
                 "title": "Produkt A",
                 "description": "19,99 €",
                 "media": {
                   "height": "SHORT",
                   "contentInfo": { "fileUrl": "https://cdn.example.com/a.jpg" }
                 },
                 "suggestions": [
                   {
                     "action": {
                       "text": "Ansehen",
                       "postbackData": "view_a",
                       "openUrlAction": { "url": "https://shop.example.com/a" }
                     }
                   }
                 ]
               },
               {
                 "title": "Produkt B",
                 "description": "24,99 €",
                 "media": {
                   "height": "SHORT",
                   "contentInfo": { "fileUrl": "https://cdn.example.com/b.jpg" }
                 },
                 "suggestions": [
                   {
                     "action": {
                       "text": "Ansehen",
                       "postbackData": "view_b",
                       "openUrlAction": { "url": "https://shop.example.com/b" }
                     }
                   }
                 ]
               }
             ]
           }
         }
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

File / Media

Send a file (image, PDF, video, audio) either by URL or by referencing a file previously uploaded to Google's RBM file store.

By URL

Use contentInfo on its own — it is its own member of Google's contentMessage oneof, not a companion to fileName. Combining them returns Google 400 INVALID_ARGUMENT (“oneof field 'content' is already set”).

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "contentInfo": {
           "fileUrl": "https://cdn.example.com/rechnungen/12345.pdf",
           "thumbnailUrl": "https://cdn.example.com/rechnungen/12345-thumb.jpg"
         }
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

Via uploaded RBM file

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491701234567",
       "content_message": {
         "uploadedRbmFile": {
           "fileName": "files/abc123",
           "thumbnailName": "files/abc123-thumb"
         }
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages

Common errors

Invalid content_message (422)

{
  "error": "Invalid content_message",
  "errors": { "text": "too_long" }
}

Stable error codes per field:

• missing — required field absent or empty
• too_long — string exceeds max length (text: 3072)
• too_many — array exceeds limit (suggestions: 11, card suggestions: 4)
• invalid_value — value not in the allowed enum (e.g. cardOrientation)
• invalid_size — carousel needs 2–10 cards
• invalid_structure — wrong shape for the given type
• missing_primary — need one of text, richCard, contentInfo, fileName, uploadedRbmFile
• multiple_primary — only one primary key allowed per message
• unknown_keys — content_message contains unsupported fields

Phone not in tenant allow-list (400)

The Allowed prefixes list reflects your tenant's configured allowed_countries at request time. Example for a tenant configured with Germany and Austria:

{
  "error": "Bad Request",
  "message": "Phone number is not in the tenant's allow-list. Allowed prefixes: +49, +43"
}

Agent not launched (422)

Returned when the agent is pre-launch and the recipient is not an accepted tester. Register the number as a tester and have them accept the invite before retrying.

{
  "error": "Agent not launched",
  "message": "Agent '…' is in status DRAFT. Before launch, only accepted testers may receive messages — register +491701234567 as a tester and have them accept the invitation."
}

Phone blacklisted (403)

Returned when the recipient is on this agent's blacklist. Two distinct cases share this response: (1) the user sent a STOP/opt-out keyword — clears once they send START/opt-in; and (2) an operator added the number manually via the admin blacklist — clears only when an operator removes it. The error body is identical in both cases.

{
  "error": "Forbidden",
  "message": "Phone number has opted out for this agent"
}

Quota exceeded (402)

Returned when the tenant's plan has a hard cap and the next send would exceed it (today: the free plan). Paid plans never return 402; they accept the send and accrue overage usage. The error_key field is the machine-readable reason — branch on it rather than parsing message.

{
  "error": "Quota exceeded",
  "error_key": "quota_exceeded_free_tier",
  "message": "Quota exceeded for plan 'free': 100/100 session(s) this period"
}

Convenience wrapper: sends a URL inside a plain text message so the RCS client auto-unfurls it into a native preview. Works for YouTube, Vimeo and direct video links — the client renders a tappable thumbnail without you having to upload or host the media yourself. An optional caption is prepended on its own two lines.

Request Body

Example

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491791234567",
       "video_url": "https://youtu.be/kg9bFxsJXlE",
       "caption": "🎥 RCS in 90 Sekunden"
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages/video

Internally this sends a plain {"text": "caption\n\nurl"} contentMessage. The response shape is identical to Send Message.

Convenience wrapper that sends a standalone image by URL — the RCS client downloads and renders it inline. Accepts an optional thumbnail_url for a lighter preview before the full image loads.

Request Body

Example

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491791234567",
       "image_url": "https://dummyimage.com/1080x720/1DA1F2/ffffff.png&text=Hallo",
       "thumbnail_url": "https://dummyimage.com/270x180/1DA1F2/ffffff.png&text=Hallo"
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages/image

Internally this sends a {"contentInfo": {"fileUrl": "…", "thumbnailUrl": "…"}} contentMessage. The response shape is identical to Send Message.

Sends 2–3 content messages in sequence to the same phone. Maps to Telekom's XL Message billing concept: up to three messages delivered within 60 seconds are consolidated into a single billing event, so you can split a richer payload (e.g. text + image + text) across multiple bubbles without paying three times.

Request Body

Example

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491791234567",
       "messages": [
         { "text": "🎉 Unsere neue Kollektion ist da!" },
         { "contentInfo": { "fileUrl": "https://dummyimage.com/1080x720" } },
         { "text": "Jetzt im Shop: https://example.com/shop" }
       ]
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages/xl

Success (201)

{
  "messages": [
    { "id": 101, "google_message_id": "…/msg-1", "message_type": "text",  … },
    { "id": 102, "google_message_id": "…/msg-2", "message_type": "file",  … },
    { "id": 103, "google_message_id": "…/msg-3", "message_type": "text",  … }
  ]
}

Partial success — Google rejects item #1 (422)

{
  "messages":   [ { "id": 101, …, "message_type": "text" } ],
  "failed_at":  1,
  "error":      "Google API Error",
  "message":    "…"
}

Single-use "goodbye" send that bypasses the per-agent blacklist for ONE message immediately after a user opts out. Authorized via the consent_audit_log_id that RCS-Box passed in the OPT_OUT forward — see the Opt-out / Opt-in section. Use it for the polite "Tschüss + STOP-Hinweis-Wiederholung"-Pattern; every subsequent send to that phone still hits the normal 403 Forbidden.

Request Body

Example

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone": "+491791234567",
       "consent_audit_log_id": 12345,
       "content_message": {
         "text": "👋 Du bist abgemeldet. Falls du's anders überlegst: einfach START zurück."
       }
     }' \
     https://api.box.rcs.jetzt/v1/agents/7/messages/final

Error responses

Testers

While an agent is in DRAFT, Google only delivers messages to registered tester phone numbers. Use these endpoints to manage the tester allow-list for each of your agents. Phones must be in the tenant's allowed country prefixes (V1: +49 only).

Lists testers registered locally for the given agent.

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents/7/testers

Response (200)

{
  "testers": [
    {
      "id": 12,
      "agent_id": 7,
      "phone": "+491791234567",
      "status": "ACCEPTED",
      "google_resource_name": "brands/acme-corp/agents/my-agent/testers/+491791234567",
      "created_at": "2026-04-20T10:00:00Z",
      "updated_at": "2026-04-20T10:05:00Z"
    }
  ]
}

Registers a phone number as a tester for the given agent. Forwards to Google Business Communications and stores the result locally. Google triggers an RCS invitation on the device.

Request Body

Example Request

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"phone":"+491791234567"}' \
     https://api.box.rcs.jetzt/v1/agents/7/testers

Response (201)

{
  "tester": {
    "id": 12,
    "agent_id": 7,
    "phone": "+491791234567",
    "status": "INVITED",
    "google_resource_name": "brands/acme-corp/agents/my-agent/testers/+491791234567",
    "created_at": "2026-04-20T10:00:00Z",
    "updated_at": "2026-04-20T10:00:00Z"
  }
}

Error — Phone not in allow-list (400)

Prefixes reflect the tenant's allowed_countries at request time (example shown for DE + AT):

{
  "error": "Bad Request",
  "message": "Phone number is not in the tenant's allow-list. Allowed prefixes: +49, +43"
}

Removes a tester both at Google and locally. If Google reports the tester as already gone (404), the local record is still removed.

Example Request

curl -X DELETE \
     -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents/7/testers/12

Response (204)

Empty response body.

Pulls the current invite status from Google for the tester and updates the local record. Use this to check whether a user accepted the invitation on their device.

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/agents/7/testers/12/status

Response (200)

{
  "tester": {
    "id": 12,
    "agent_id": 7,
    "phone": "+491791234567",
    "status": "ACCEPTED",
    "google_resource_name": "brands/acme-corp/agents/my-agent/testers/+491791234567",
    "created_at": "2026-04-20T10:00:00Z",
    "updated_at": "2026-04-20T10:15:00Z"
  }
}

Brands

A brand represents the legal entity sending RCS messages (e.g. Acme Ltd.). Each tenant maps to one Google brand; agents live underneath it. Public endpoints let customers read brand state. Mutating actions (sync, document upload, vendor calls) are performed by Railslove operators via the admin UI.

Operator- und Vendor-Endpunkte siehe Internal API bzw. Vendor API am Seitenende.

Lists brands visible to the authenticated tenant.

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/brands

Response (200)

{
  "brands": [
    {
      "google_brand_id": "brands/abc",
      "display_name": "Acme Ltd.",
      "verification_state": "VERIFIED",
      "synced_at": "2026-06-02T12:00:00Z"
    }
  ]
}

Returns a single brand by its Google brand id (e.g. brands/abc).

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/brands/brands/abc

Response (200)

{
  "brand": {
    "google_brand_id": "brands/abc",
    "display_name": "Acme Ltd.",
    "verification_state": "VERIFIED",
    "synced_at": "2026-06-02T12:00:00Z"
  }
}

Returns the current brand-level verification state mirrored from Google.

Response (200)

{
  "google_brand_id": "brands/abc",
  "verification_state": "VERIFIED",
  "verification_synced_at": "2026-06-02T12:00:00Z"
}

Launch

Launch is the per-carrier rollout. Once an agent is VERIFIED, Railslove submits a launch request listing the target carriers and answering a questionnaire about message volume, opt-in flow, and use case. Google then forwards the request to each carrier; carrier states transition independently to LAUNCHED.

Operator- und Vendor-Endpunkte siehe Internal API bzw. Vendor API am Seitenende.

Operator checklist

[ ] Brand exists & synced from Google (GET /v1/brands)
[ ] Brand verification contact filled (partner + brand + website)
[ ] Supporting PDFs uploaded (1–5 PDFs, ≤50MB each)
[ ] Agent created at Google with all required fields
    (logo, hero, color, privacy, terms, website, billing, region)
[ ] At least one Tester registered + accepted invite
[ ] STOP flow tested with tester (operator confirms)
[ ] Agent asset URLs HTTPS-reachable (UI button runs HEAD probe)
[ ] Verification submitted (requestVerification) → state VERIFIED
[ ] Carriers selected
[ ] Launch questionnaire complete
[ ] Launch submitted (requestLaunch) → poll getLaunch until LAUNCHED

Returns the agent's overall launch state plus a per-carrier breakdown. :id is the local Agent ID (Rails bigint primary key). Use this to monitor rollout progress.

Response (200)

{
  "status": "LAUNCHED",
  "launch_details": [
    {
      "region": "regions/dt-germany",
      "launch_state": "LAUNCH_STATE_LAUNCHED",
      "update_time": "2026-06-01T08:30:00Z",
      "comment": null
    }
  ]
}

Reicht die Launch-Questionnaire-Antworten als Customer ein. Jeder Aufruf überschreibt den vorherigen Draft. Railslove sichtet, übernimmt und sendet die Daten anschließend an Google.

Example Request

curl -X POST -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "primary_contact_name": "Joe",
       "primary_contact_email": "joe@example.com",
       "opt_in_description": "User signs up on our website",
       "opt_out_description": "Reply STOP",
       "trigger_description": "Order confirmation",
       "interaction_description": "Customer service",
       "video_url": "https://example.com/demo.mp4",
       "screenshot_url": "https://example.com/screenshot.png"
     }' \
     https://api.box.rcs.jetzt/v1/agents/<agent_id>/launch_questionnaire_draft

Response (201)

{
  "agent_id": 19,
  "google_agent_id": "brands/acme/agents/local-1",
  "submitted_at": "2026-06-03T01:00:00Z",
  "draft": {
    "primary_contact_name": "Joe",
    "primary_contact_email": "joe@example.com",
    ...
  }
}

Validation errors (422)

primary_contact_email is required and must be a valid email. video_url and screenshot_url are optional but must begin with http:// or https:// when provided.

{
  "error": "Validation failed",
  "errors": { "primary_contact_email": "invalid_format" }
}

Gibt den aktuell eingereichten (aber noch nicht von Railslove übernommenen) Draft zurück. draft ist null, wenn nichts eingereicht wurde oder Railslove den Draft bereits übernommen oder verworfen hat.

Response (200)

{
  "agent_id": 19,
  "google_agent_id": "brands/acme/agents/local-1",
  "submitted_at": "2026-06-03T01:00:00Z",
  "draft": {
    "primary_contact_email": "joe@example.com",
    "trigger_description": "Order confirmation"
  }
}

Carriers

Lists the German carriers RCS-Box has contracts with (mirrored from Google's regions catalog). Used when selecting targets for launch.

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     https://api.box.rcs.jetzt/v1/carriers

Response (200)

{
  "carriers": [
    {
      "slug": "dt-germany",
      "name": "Germany: DT",
      "google_region_name": "regions/dt-germany",
      "management_type": "GOOGLE_MANAGED"
    }
  ]
}

Capabilities

Checks whether a phone number is reachable via RCS for the given agent. Returns the list of RCS features that Google reports for the device. Use this before sending to avoid wasted billable sends to non-RCS numbers.

Query parameters

Example Request

curl -H "Authorization: Bearer $API_KEY" \
     "https://api.box.rcs.jetzt/v1/agents/7/capabilities?phone=%2B491791234567"

Response — RCS-capable (200)

{
  "rcs_enabled": true,
  "features": [
    "RICHCARD_STANDALONE",
    "RICHCARD_CAROUSEL",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL"
  ]
}

Response — not RCS-capable (200)

{
  "rcs_enabled": false,
  "features": []
}

Checks reachability for up to 100 phone numbers in a single call. Useful for pre-filtering large recipient lists. Returns one result per input phone, in the same order as the request.

Request body

Example Request

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"phones":["+491791234567","+491791234568","+12025550100"]}' \
     https://api.box.rcs.jetzt/v1/agents/7/capabilities/batch

Response (200)

{
  "results": [
    { "phone": "+491791234567", "rcs_enabled": true },
    { "phone": "+491791234568", "rcs_enabled": false },
    { "phone": "+12025550100",  "rcs_enabled": false, "skipped": "not_in_allowlist" }
  ]
}

Error responses

Webhooks

Each tenant may configure a webhook_url (set by your administrator). When Google sends an incoming user message for one of your agents, RCS-Box forwards the payload to that URL. The shape matches Google's RCS Business Messaging webhook format. Opt-out / opt-in messages are also forwarded, with an extra rcs_box_action field; these forwards require an acknowledgement from your endpoint — see the Opt-out / Opt-in section. Delivery events (DELIVERED, READ) are also forwarded as-is — without an rcs_box_action field — so you can match them against your outbound-message log via event.messageId.

Request format

RCS-Box forwards every callback as an HTTP POST to your configured webhook_url. The body is the raw JSON payload — no form-encoding, no wrapper. The connection timeout is 30 seconds; slower responses are retried via Sidekiq (up to 3× for ack'd flows; see Opt-out / Opt-in).

Example forwarded request

POST /your/webhook/path HTTP/1.1
Host: your-domain.example.com
Content-Type: application/json
X-RCS-Box-Signature: 5e7c9a…b3f1

{
  "agent": "brands/acme-corp/agents/my-agent",
  "senderPhoneNumber": "+491701234567",
  "message": { "text": "Hello!" }
}

Signature header

Every forwarded request carries an X-RCS-Box-Signature header. The value is a lowercase hex-encoded HMAC-SHA256 computed over the request body (the JSON payload as serialized by RCS-Box), keyed with your API key. Verify it before trusting the payload.

# Ruby
require "openssl"
expected = OpenSSL::HMAC.hexdigest("SHA256", api_key, request.raw_post)
actual   = request.headers["X-RCS-Box-Signature"]
reject unless ActiveSupport::SecurityUtils.secure_compare(expected, actual)

Event types

Google sends three callback shapes. You can distinguish them by the top-level keys present in the payload. Only user messages are forwarded to your webhook_url; delivery events stay internal.

Opt-out / Opt-in

When a user replies with a message whose first word (case-insensitive, after trimming whitespace) matches one of the keywords below, RCS-Box automatically updates the per-agent blacklist and forwards the original payload to your webhook_url with an extra rcs_box_action field set to "OPT_OUT" or "OPT_IN".

Example forward (opt-out)

{
  "agent": "brands/acme-corp/agents/my-agent",
  "senderPhoneNumber": "+491701234567",
  "userMessage": { "text": "STOP" },
  "rcs_box_action": "OPT_OUT",
  "consent_audit_log_id": 12345
}

The consent_audit_log_id is your handle for a one-time "goodbye" send via POST /messages/final — useful for the "Tschüss + STOP-Hinweis-Wiederholung"-Pattern that the per-agent blacklist would otherwise block.

Tenant acknowledgement (required)

For every forward with rcs_box_action set, your endpoint must respond 200 OK with the JSON body {"acknowledged": true} within 30 seconds. The acknowledgement is what proves to RCS-Box (and to your DSGVO audit trail) that you have processed the consent change in your own system.

HTTP/1.1 200 OK
Content-Type: application/json

{ "acknowledged": true }

First-time OPT_IN (no prior blacklist entry)

OPT_IN handling is symmetric: even when the user has never been on your blacklist, a START message still produces a consent_audit_logs row, still gets forwarded with "rcs_box_action": "OPT_IN", and still requires your {"acknowledged": true} response. The internal remove-from-blacklist step runs unconditionally when the START webhook arrives and is a no-op when there's no prior entry; the audit log is the part that captures the explicit consent. Use the forwarded event to register a first-time opt-in in your own system — e.g. flag the contact as "consent given by RCS reply" in your CRM.

How to test as a tenant

End-to-end you need three things: a public URL that captures incoming HTTP requests, a configured webhook_url on your tenant, and an accepted tester number that can send real RCS messages to one of your agents.

1. Set up a capture URL

Open webhook.site — you get a unique URL like https://webhook.site/<uuid>. Keep the tab open; every request the URL receives appears live with full body and headers.

2. Configure your tenant webhook_url

Ask your administrator to set the webhook_url on your tenant to the webhook.site URL from step 1. The setting lives in the admin tenant edit form.

3. Add and accept a tester

Pick an agent, register a tester phone number you control, and accept the invitation on that device. You can do this via POST /v1/agents/:agent_id/testers or in the admin UI.

4. Trigger callbacks

From the tester device, send the following messages to your agent:

5. Verify the signature

Each forward carries an X-RCS-Box-Signature header. Recompute it locally with your API key over the raw request body (see signature header). If the values match you know the payload is from RCS-Box and untampered.

Error Handling

All errors return a consistent JSON format with an error and message field.

{
  "error": "Unauthorized",
  "message": "API key required"
}

HTTP Status Codes

Rate Limits

Requests to the Google RCS API are subject to rate limiting. RCS-Box automatically retries rate-limited requests (HTTP 429) with exponential backoff up to 3 times.

Phone Number Format

All phone numbers must be provided in E.164 format. Each tenant has an allow-list of country prefixes; V1 defaults to Germany only (+49). Formatting characters (spaces, dashes) are stripped before validation; numbers outside the tenant's allow-list are rejected with HTTP 400.

Brand admin

Re-fetches the brand from Google Business Communications and refreshes the local mirror. Triggered by Railslove operators after Google updates the brand contact or verification status.

Updates local brand metadata (display name, partner contact, website). Does not write to Google; use the vendor endpoints for that.

Uploads a supporting PDF (1–5 per brand, ≤50 MB each) used by Google to verify the legal entity. Stored in encrypted blob storage and attached to subsequent verification requests.

Removes an uploaded brand PDF.

Submits the brand for verification. Internally picks the brand's first agent (Google caches verification per-brand), calls vendor :requestVerification first, then uploads the brand's PDF attachments onto the verification record. Operator-only; once-per-brand.

Polls Google for the latest verification status of the brand and updates the local mirror. Refresh ist manuell — Operator klickt im Admin auf "Refresh from Google". Eine Background-Polling-Variante ist als Follow-up geplant.

Submits the launch request to Google. Gated by readiness (verified + carriers selected + questionnaire complete + assets reachable). Calls vendor :requestLaunch.

Adds additional carriers to an already-launched agent. Calls vendor PATCH to amend the launch document with the new carrier list.

Polls Google for the latest per-carrier launch state and updates the local mirror.

Updates the launch questionnaire fields (use case, opt-in flow, monthly volume, sample messages) stored locally and sent with the launch request.

Records operator confirmation of manual checklist items (STOP flow tested, tester accepted, etc.) before submitting the launch.

Runs a HEAD probe against the agent's asset URLs (logo, hero, privacy, terms, website) to confirm HTTPS reachability and reasonable content types. Surfaces failures inline in the admin UI.

Re-fetches the carrier/regions catalog from Google and refreshes the local mirror. Run manually after Google announces new carriers.

Brand vendor

Underlying Google Business Communications call used by /admin/brands/:id/sync. Not callable by customers; documented for transparency.

Fetches a single Google brand resource. Used by sync to populate display_name and verification state.

Manual one-off creation of a new brand at Google. Performed by a Railslove operator during tenant onboarding; the resulting google_brand_id is then stored on the tenant.

Underlying Google call that asks Google to verify the agent.

Reads the current verification document at Google. Used by refresh.

Uploads a single PDF attachment to Google. Called per document during submission, after :requestVerification has created the verification record — the upload docks the BAL onto that record.

Removes a previously uploaded attachment at Google.

Underlying Google call to launch an agent across the listed carriers. Body includes the questionnaire payload.

Reads the current launch document at Google, including per-carrier state. Used by refresh.

Amends an existing launch document (e.g. to add carriers). Called by add_carriers.

Underlying Google call returning the carriers/regions catalog.