RCS

The seven RCS-API offers the possibility to integrate the powerful functions of RCS into your application and thus enable rich, interactive communication with your users. This documentation describes the various endpoints, parameters and functions of the RCS API in detail. Discover the many possibilities RCS offers to enhance messaging, file sharing, location sharing and much more.

To send RCS messages, you need your own RCS service, also called an agent. It is your verified sender with brand name, logo and colors, and it is activated for every network operator you want to send RCS messages to. You set up the service yourself in the dashboard.

1
Create an RCS service
In the dashboard, go to Settings → Sender IDs and click Create RCS Service to set up your brand name, logo, colors and contact details. For a step-by-step guide, see the RCS quickstart.
2
Integrate RCS API
Once your service has been created, you can start implementing the API straight away.
3
Test RCS
Add your test numbers to the service. Until your service is live, RCS messages can only be sent to these numbers.
4
Go live
Submit your service in the dashboard for activation with the network operators you want. Verification and the review by the network operators can take several weeks. All requirements are listed in Launch your RCS service.
5
Send RCS 🚀
You're ready to go and can start sending RCS messages right away!

POST/api/rcs/messages

Send RCS

This endpoint allows you to send RCS messages to users. Before sending an RCS, you should ideally query the capabilities of the phone number to ensure the best possible user experience.

Parameters

Name
to
Type
string
Description
The recipient number for your RCS message. This can also be a contact name or a group name.
Name
text
Type
string
Description
Text of the RCS message. To send a simple RCS message (without images, suggested replies, etc.), only enter the plain text of the message here. Otherwise, use an RCS object.
Name
from
Type
string
Optional
Optional
Description
The unique ID of your agent. You can view this in the Settings of your account. If not specified, the first RCS-capable sender will be used.
Name
delay
Type
timestamp
Optional
Optional
Description
Date/time for delayed dispatch. Optionally Unix timestamp or a timestamp in the format yyyy-mm-dd hh:ii.
Name
ttl
Type
integer
Optional
Optional
Description
Specifies the validity period of the RCS in minutes. The default is 2880, i.e. 48 hours.
Name
label
Type
string
Optional
Optional
Description
Optionally set a separate label for each RCS so that you can assign it to your statistics. Max. 100 characters, permitted characters: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Activate click and performance tracking for URLs found in the RCS text. This also activates the URL shortener.
Name
foreign_id
Type
string
Optional
Optional
Description
Enter your own ID for this message. You will receive the foreign_id in turn for callbacks for status reports etc. Max. 64 characters, permitted characters: a-z, A-Z, 0-9, .-_@.
Name
fallback
Type
enum
Description
If it is not possible to send an RCS message because, for example, the recipient's device does not support RCS, the message can be automatically sent through an alternative channel. If no fallback is specified, it is disabled.
Either send one of these values:
sms - Sends an SMS with the text of the RCS message as content webview - Sends an SMS with a link to a web view of the RCS message
Or send a JSON object:
{ "type": "sms", "text": "Here is the text of the SMS", "from": "sender" }

POST

/api/rcs/messages

curl -X POST "https://gateway.seven.io/api/rcs/messages" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -d "text=Hello World!" \
    -d "to=49176123456789"

{
    "success": "100",
    "total_price": null,
    "balance": 3218.988,
    "debug": "false",
    "sms_type": "direct",
    "messages": [
        {
            "id": "77233319353",
            "sender": "myfancyagent",
            "recipient": "49176123456789",
            "text": "Hello World!",
            "encoding": "gsm",
            "label": null,
            "parts": 0,
            "udh": null,
            "is_binary": false,
            "price": 0,
            "channel": "RCS",
            "success": true,
            "error": null,
            "error_text": null
        },
        {
            "id": "77233319354",
            // ...
        }
    ]
}

DELETE/api/rcs/messages/:id

Delete RCS

You can revoke an RCS message that has not yet been delivered. This API immediately returns a successful response, regardless of whether the message has been deleted or not. Revocation is only possible if the end device has the REVOCATION capability.

You cannot delete an RCS message if you have specified SMS or Rich SMS as a fallback.

Path parameters

Name
Message ID
Type
string
Description
The ID of the message to be deleted.

Request

DELETE

/api/rcs/messages/123456

curl -X DELETE "https://gateway.seven.io/api/rcs/messages/123456" \
    -H "X-Api-Key: YOUR_API_KEY"

Response

{
    "success": true
}

POST/api/rcs/events

Events

Send an event to a phone number to provide users with a more authentic conversational experience. After receiving a message, you should send the event READ and then IS_TYPING accordingly within a reasonable time.

Parameter

Name
to
Type
string
Union
Description
The phone number to which you want to send the event.
Name
msg_id
Type
string
Union
Description
The ID of the received RCS to which you want to send the event. If not specified, the event is automatically sent to the last RCS message received.
Name
event
Type
enum
Description
The event to be sent. Can have one of the following values:
Show events
IS_TYPING - The agent is currently writing READ - The message sent by the user has been read

Request

POST

/api/rcs/events

curl -X POST "https://gateway.seven.io/api/rcs/events" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -d "to=49176123456789" \
    -d "event=IS_TYPING" \
    -d "from=myfancyagent"

Response

{
    "success": true
}

GET/api/rcs/agents

List agents

This endpoint returns a list of all RCS agents available in your account, including generic (publicly usable) agents. The response includes the current status as well as metadata for each agent.

Response fields

Name
agents
Type
array
Description
Array containing all RCS agents available for your account.
Name
agents[].id
Type
string
Description
The unique ID of the agent. This is used as the from parameter when sending an RCS message.
Name
agents[].display_name
Type
string
Description
The display name of the agent visible to the recipient.
Name
agents[].status
Type
enum
Description
The current status of the agent. Possible values:
pending - Agent has been created but not yet submitted for review test - Agent can only send to the configured test numbers launched - Agent has been launched and can send RCS messages in production approved - Agent has been approved by the network operators
Name
agents[].logo_url
Type
string | null
Description
URL to the agent's logo. Can be null or an empty string if no logo has been uploaded.
Name
agents[].created
Type
string
Description
Creation date of the agent in the format yyyy-mm-dd hh:ii:ss.
Name
agents[].is_generic
Type
boolean
Description
Indicates whether this is a generic agent. Generic agents are provided by seven and can be used by multiple customers, instead of an agent created exclusively for your account.

Request

GET

/api/rcs/agents

curl "https://gateway.seven.io/api/rcs/agents" \
    -H "X-Api-Key: YOUR_API_KEY"

Response

{
    "agents": [
        {
            "id": "seven_demo_ja2E9Comde",
            "display_name": "seven.io Demo",
            "status": "launched",
            "logo_url": "https://agent-logos.storage.googleapis.com/_/lx8puyryRsdJQKrPufyE0ngg",
            "created": "2024-09-27 10:07:50",
            "is_generic": false
        },
        {
            "id": "werkstattdialogde_6C4d6081",
            "display_name": "WerkstattDialog.de",
            "status": "approved",
            "logo_url": null,
            "created": "2024-09-13 06:04:47",
            "is_generic": true
        }
    ]
}

RCS

Create an RCS service

Integrate RCS API

Test RCS

Go live

Send RCS 🚀

Send RCS

Parameters

Delete RCS

Path parameters

Request

Response

Events

Parameter

Request

Response

List agents

Response fields

Request

Response