NAV
shell

Getting Started

Rich Communication Services (RCS) is an advanced messaging protocol that enables businesses to send interactive, media-rich messages to customers. The Generic RCS API allows you to integrate RCS messaging into your applications, letting you send branded text messages, images, videos, and Rich Cards with interactive suggestions (buttons) to end-users on RCS-enabled devices. With RCS, you can deliver a more engaging experience than SMS by including features like suggested reply buttons, action buttons (e.g. open a URL, dial a number), and calendar event prompts.

To use the RCS API, you will need an account with Generic and an RCS agent provisioned for your business (identified by an agentId). Please contact our support team or your sales representative to obtain your RCS agent credentials and API access. Once you have your account and agent set up, you can start sending RCS messages using our RESTful API.

Base URL: https://api.genericmobile.se/Rcs/api/v1

All API endpoints described in this documentation are relative to the base URL above. For example, a POST request to send a message would be made to https://api.genericmobile.se/Rcs/api/v1/Message.

Messages sent via the RCS API will be processed through the Generic messaging platform, which handles both RCS and SMS messages.

Authentication

Authentication with API key

  curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
    -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
    -H 'Content-Type: application/json' \
    -d '{
          "agentId": "your_agentId",
          "number": ["+46701234567"],
          "messageType": "TextMessage",
          "text": "Hello from RCS!\nThis is a test message."
        }'

  200 OK
  {
    "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff002"
  }

All requests to the RCS API require authentication via an API key. This ensures that only authorized users can send messages or access information.

Bearer API Key

Authenticate your requests by including an Authorization header with the value Bearer , replacing with your actual key. API keys are generated and managed through our customer platform.

401 Unauthorized

If your request lacks a valid API key or proper permissions, you'll receive a 401 Unauthorized response. Verify that your authentication details are correct and have appropriate permissions.

Sending RCS Messages

Example 1: Send a Simple Text Message

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
         "+46701234567",
         "+46702345678"
        ],
        "messageType": "TextMessage",
        "text": "Hello! This is an example of an RCS text message."
      }'

200 OK
{
  "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff000"
}

The RCS API allows you to send rich messages to one or more recipients. A single API request can deliver a message to multiple phone numbers. You can send simple text-only messages or more interactive content such as rich cards and Carousel with images and suggested buttons.

POST /Message

In all cases, the request is made via HTTPS POST to the /Message endpoint. At minimum, you must specify your RCS agent identifier, the recipient's number, the type of message, and the content.

When a message is successfully sent, a tagId is always returned. To retrieve detailed information about the message—such as delivery status, read receipts, and other metadata—use the Fetch Tag Statistics endpoint.

Text Message

In its simplest form, to send a plain text message, you would include the following required fields in the JSON body: agentId, number, messageType, and text.

Below is a summary of the key parameters used in the RCS API requests for sending a simple Text Message:

Parameter Required Type Description
agentId Yes String The unique identifier of your RCS agent. This identifies the sender of the RCS message (equivalent to the "From" field in SMS).
number Yes Array of String One or more recipient phone numbers in international format (E.164). These are the end‑users who will receive the message.
tag No String User-defined label.
messageType Yes String TextMessage
text Yes String The text content of the message. This field is required when sending a text message. You can include a maximum of 3072 characters.
suggestedActions + No List of Object A list of suggested action objects. (A maximum of 11 combined suggested replies and actions is allowed.)
suggestedReplies + No List of Object A list of suggested reply objects. (A maximum of 11 combined suggested replies and actions is allowed.)

Example 2: Send a Rich Card Message

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46702345678",
          "+46701234567"
        ],
        "messageType": "RichCard",
        "suggestedActions": [
          {
            "openUrlAction": {
              "url": "https://www.Generic.se/"
            },
            "text": "Visit Website",
            "postbackData": "visitWebsite"
          }
        ],
        "richCardContent": {
          "height": "short",
          "orientation": "VERTICAL",
          "thumbnailImageAlignment": "LEFT",
          "title": "Welcome to Generic!",
          "description": "Precise messaging in smart flows Accelerate the customer journey, reach the right person at the right moment, and let us make your life significantly easier.",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2023/06/GENERIC-startsida-3uspar-soveraldrig-300x254.png",
          "suggestedReplies": [
            {
              "text": "Try me!",
              "postbackData": "tryMe"
            }
          ]
        }
      }'

200 OK
{
  "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff000"
}

Rich Card

Rich Cards in RCS combine media, text, and interactive suggestions into a single message. They are designed to focus on a specific topic and provide users with clear action options,creating a richer and more engaging messaging experience.

A Rich Card can include:

These fields are optional, but at least one of the first three must be included.

Rich Cards support various media formats,including JPEG, PNG, GIF, as well as videos in formats like MP4, WebM, and MPEG-4. You can also choose different media heights depending on how you want the card to be displayed.

Images: - image/jpeg - image/jpg - image/gif - image/png

Video: - video/h263 - video/m4v - video/mp4 - video/mpeg - video/mpeg4 - video/webm

It is also possible to upload a file directly via the following endpoint: https://api.genericmobile.se/Rcs/api/v1/UploadFile/{agentId} This can be used as an alternative to specifying a public URL for the file or image. By using Rich Cards, you can create dynamic and visually appealing messages that simplify interaction and enhance user engagement directly within the messaging app.

Parameter Required Type Description
agentId Yes String The unique identifier of your RCS agent. This identifies the sender of the RCS message (equivalent to the "From" field in SMS).
number Yes Array of String One or more recipient phone numbers in international format (E.164).
tag No String User-defined label.
messageType Yes String RichCard
suggestedActions + No List of Object A list of suggested action objects. (A maximum of 11 combined suggested replies and actions is allowed.)
suggestedReplies + No List of Object A list of suggested reply objects. (A maximum of 11 combined suggested replies and actions is allowed.)
richCardContent + Yes Object richCardContent object

Example 3: Send a Carousel Message


curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your_agentId",
    "number": [
      "+46701234567",
      "+46709876543"
    ],
    "messageType": "Carousel",
    "carouselContent": {
      "cardWidth": "MEDIUM",
      "richCardContents": [
        {
          "height": "TALL",
          "orientation": "HORIZONTAL",
          "thumbnailImageAlignment": "RIGHT",
          "title": "Carousel 1",
          "description": "This is a Carousel example",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2023/06/GENERIC-startsida-3uspar-hjalpermedallt.png",
          "suggestedActions": [
            {
              "text": "Visit Homepage!",
              "postbackData": "VisitHomepage",
              "openUrlAction": {
                "url": "https://www.generic.se/"
              }
            }
          ]
        },
        {
          "title": "Carousel 2",
          "description": "This is a Carousel example with an image from fileUpload",
          "fileId": "files/m6umqu6gXMza1bcde2FGHIJKLMn3opqr",
          "suggestedActions": [
            {
              "text": "Call support",
              "postbackData": "support",
              "dialAction": {
                "phonenumber": "+46709876543"
              }
            }
          ]
        },
        {
          "title": "Carousel 3",
          "description": "This is a Carousel example whit an image from fileUrl",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2022/10/GENERIC-Tjanster-GenericDocs-Page-1-1146x752-2-768x504.png"
        }
      ]
    }
  }'

200 OK
{
  "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff000"
}

Carousel in RCS makes it possible to display multiple Rich Cards in a continuous view, allowing users to scroll through different options and interact with each card individually. This is perfect for presenting multiple products, services, or choices in a structured and engaging way.

A Carousel can contain between 2 and 10 Rich Cards, where each card follows the same content and height requirements as a regular Rich Card. The cards can include media, titles, descriptions, and suggested actions. The height of the first few cards in the carousel determines the height of all the cards, which can impact how much content is visible without being truncated.

If the content doesn't fit on the screen, the cards may be automatically truncated based on the following logic:

The description is shortened to one line. The title is shortened to one line. Suggestions that don't fit are removed, starting from the end of the list. The description is removed entirely. The title is removed entirely. To avoid truncation, it is recommended to keep titles and descriptions short and balance the content across cards. If necessary, larger cards can be placed first to reduce the risk of truncation in subsequent cards.

By using carousels, you can create interactive and visually appealing messages that make it easier for users to compare options and make quick decisions — directly within the messaging app.

Parameter Required Type Description
agentId Yes String The unique identifier of your RCS agent. This identifies the sender of the RCS message (equivalent to the "From" field in SMS).
number Yes Array of String One or more recipient phone numbers in international format (E.164).
tag No String User-defined label.
messageType Yes String Carousel
suggestedActions + No List of Object A list of suggested action objects. (A maximum of 11 combined suggested replies and actions is allowed.)
suggestedReplies + No List of Object A list of suggested reply objects. (A maximum of 11 combined suggested replies and actions is allowed.)
carouselContent + Yes Object List of richCardContents and cardWidth

Suggestions

Suggested Replies and Actions Limits in Rich Cards

Each individual rich card — including those within a carousel — can contain up to 4 suggested replies or actions. In addition to those within the cards, you can also include up to 11 suggested replies or actions outside the cards (i.e., global suggestions).

You may choose to use both: For example, 4 suggestions inside each card, plus up to 11 outside the cards. These limits apply independently.

Suggested Actions

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567",
          "+46702345678"
        ],
        "messageType": "Text",
        "text": "Hello! This is an RCS text message with different Suggested actions.",
        "suggestedActions": [
         {
            "text": "Call Support",
            "postbackData": "callSupport",
            "dialAction":
            {
              "phoneNumber": "+46701234567"
            }
          },
          {
            "text": "View location with LatLng",
            "postbackData": "viewLocationWithLatLng",
            "viewLocationAction":
            {
              "LatLng": 
              {
                "Longitude": "15.081701",
                "Latitude" : "59.369565"
              }
            }
          },
          {
            "text": "View location with query",
            "postbackData": "viewLocationWithQuery",
            "viewLocationAction":
            {
              "query": "United Spaces Klarabergsviadukten 63, Stockholm"
            }
          },
          {
            "text": "Rcs Meeting",
            "postbackData": "rcsMeeting",
            "createCalendarEventAction":
            {
              "title": "Rcs Meeting",
              "description": "Discuss project updates and next steps.",
              "startTime": "2024-11-30T10:00:00Z",
              "EndTime": "2024-11-30T11:00:00Z"
            }
          },
          {
            "text": "Login",
            "postbackData": "logIn",
            "openUrlAction": 
            {
              "url": "https://www.Generic.se/"
            }
          },
          {
            "text": "Share phone location",
            "postbackData": "sharePhoneLocation",
            "ShareLocationAction": {}
          }
        ]
      }'

200 OK
{
  "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff000"
}

SuggestedActions allows you to provide interactive buttons that perform actions when clicked. Each suggested action is represented as an object containing one of the specific action definitions along with common optional fields, as described below:

Parameter Required Type Description
Text Yes String The display text shown on the suggested action button.
PostbackData Yes String Data returned to your agent when the suggested action is clicked. Useful for tracking or responding to user interactions.
Action Yes Action Object Substitute "Action" with the action you intend to use.

Each suggested action object should specify exactly one action type (e.g., openUrlAction, dialAction, etc.), accompanied by required fields Text and PostbackData as necessary.

DialAction: - Defines an action to initiate a phone call to a specified number.

ViewLocationAction: - Defines an action to view a specific geographic location on a map.

CreateCalendarEventAction: - Defines an action to create a calendar event.

OpenUrlAction: - Defines an action to open a URL when the button is clicked.

ShareLocationAction: - Defines an action allowing the recipient to share their location.

DialAction

Opens the user's default dialer app with the agent-specified phone number filled in.

Field Required Type Description
phoneNumber Yes String The phone number in international format (E.164) to be dialed when the action is triggered (e.g., +46701234567).

ViewLocationAction

Opens the user's default map app and selects the agent-specified location or searches around the user's location given an agent-specified query.

Field Required Type Description
latLong + No LatLng The latitude/longitude pair specifying the exact location to select on the map.
label No String A label describing the location specified by latLong.
query No String A query string for location search. Supported only on Android Messages clients. If specified, a search is performed around the user's current location instead of selecting a fixed point.

CreateCalendarEventAction

Opens the user's default calendar app with the agent-specified event details pre-filled.

Field Required Type Description
startTime Yes String (RFC 3339) Event start time, formatted according to RFC 3339 (e.g., 2024-10-02T15:01:23Z).
endTime Yes String (RFC 3339) Event end time, formatted according to RFC 3339 (e.g., 2024-10-02T16:01:23Z).
title Yes String Event title. Maximum 100 characters.
description Yes String Event description. Maximum 500 characters.

OpenUrlAction

Opens the user's default web browser app to the specified URL.

Field Required Type Description
url Yes String URL to open. Must be a valid URI (RFC 3986). Maximum 2048 characters.

ShareLocationAction

Opens the RCS user's default map application to allow the user to share their current location with your agent. This action does not require any additional parameters.

Suggested Replies

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "yourAgentId",
        "number": ["+46701234567"],
        "messageType": "textMessage",
        "text": "Hello! Do you find this helpful?",
        "suggestedReplies": [
          {
            "text": "Yes!",
            "postbackData": "yes"
          },
          {
            "text": "No!",
            "postbackData": "no"
          }
        ]
      }'

200 OK
{
  "totalSms": 0,
  "totalRcs": 2,
  "rcs": [
        {
            "number": "+46701234567",
            "type": "RCS",
            "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff001",
            "status": "SENT"
        }
    ],
  "smsNumbers": []
}

SuggestedReplies is a feature within RCS that allows users to quickly choose from predefined response options directly in the messaging app. This creates a smoother and more structured conversational experience, where users can select a response with a single tap instead of typing a manual message.

By implementing Suggested Replies, a simple conversation can turn into an interactive experience, similar to an app, where users are guided through different choices. To use Suggested Replies, a callbackUrl must be set up for the agent registered with Generic. Contact Generic's sales team for assistance with this. Generic will push incoming replies in real-time, allowing you to handle interactions independently.

Callback URL

Example data

{
  "AgentId": "Your_AgentId",
  "MessageId": "deadc0de-2bad-c4fe-feed-beefca1ff00d",
  "Time": "2025-03-18T14:30:00Z",
  "SenderPhoneNo": "+46701234567",
  "PostbackData": "trackPackage",
  "Text": "I'd like to track my package",
  "Type": "ACTION"
}

The Callback URL feature allows you to receive responses directly from your customers. To enable this feature, you must contact Generic to set up a Callback URL for your RCS agent. Once configured, all incoming replies from end-users will be automatically pushed to your specified URL. This enables you to handle and process user responses in real-time within your own systems, providing greater flexibility and control over customer interactions.

The following table describes the data pushed to your Callback URL:

Parameter Type Description
AgentId String Identifier of your RCS agent.
MessageId String Unique identifier for the message.
Time Timestamp Time when the message or action was received.
SenderPhoneNo String Phone number of the responding end-user.
PostbackData String Data originally sent to track interactions.
Text String Content of the user's reply, if applicable.
Type String Type of interaction (e.g., text, action, read receipt).

Fallback Sms

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
         "+46701234567",
         "+46702345678"
        ],
        "smsFallbackText": "This text is sent to phones that do not support RCS"
        "messageType": "textMessage",
        "text": "Hello! This is an example of an RCS text message."
      }'

200 OK
{
  "tagId": "deadc0de-2bad-c4fe-feed-beefca1ff000"
}

To guarantee message delivery to recipients without RCS capability, use the SmsFallBackText property in your request body. When included, if the recipient's phone does not support RCS, the message specified in SmsFallBackText is automatically sent as an SMS instead.

Rcs examples

Example 1: Simple Text Message with two suggested replies

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
-H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
-H "Content-Type: application/json" \
-d '{
  "agentId": "your_agentId",
  "number": [
    "+46701234567"
  ],
  "messageType": "TextMessage",
  "textMessage": {
    "text": "Was this helpful?"
  },
  "suggestedReplies": [
    {
      "text": "Yes",
      "postbackData": "Generic"
    },
    {
      "text": "No",
      "postbackData": "Generic"
    }
  ]
}'

Simple Text Message Example

Example 1: Text Message with two suggested replies

Example 2: Simple Text Message with three suggested actions

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567"
        ],
        "messageType": "TextMessage",
        "textMessage": {
          "text": "More information about Generic"
        },
        "suggestedActions": [
          {
            "text": "Visit Website",
            "postbackData": "website",
            "openUrlAction": {
              "url": "https://www.Generic.se/"
            }
          },
          {
            "text": "Call Generic",
            "postbackData": "callGeneric",
            "dialAction": {
              "phoneNumber": "+46701234567"
            }
          },
          {
            "text": "Find Generic",
            "postbackData": "findGeneric",
            "viewLocationAction": {
              "query": "United Spaces Klarabergsviadukten 63, Stockholm"
            }
          }
        ]
      }'


Example 2: Text Message with three suggested actions

Rich Card Example

Example 3: Vertical Rich Card featuring one suggested action and one suggested reply.

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567"
        ],
        "messageType": "RichCard",
        "richCardContent": {
          "height": "TALL",
          "orientation": "VERTICAL",
          "title": "Your Package is on its way!",
          "description": "Did you know that you can reschedule your package delivery?",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2023/06/GENERIC-startsida-3uspar-soveraldrig-300x254.png",
          "suggestedReplies": [
            {
              "text": "Reschedule delivery",
              "postbackData": "rescheduleDelivery"
            }
          ],
          "suggestedActions": [
            {
              "text": "Track package",
              "postbackData": "trackPackage",
              "viewLocationAction": {
                "query": "United Spaces Klarabergsviadukten 63, Stockholm"
              }
            }
          ]
        }
      }'

Example 4: Horizontal Rich Card featuring a left-aligned thumbnail image, one suggested action, and one suggested reply.

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567"
        ],
        "messageType": "RichCard",
        "richCardContent": {
          "orientation": "HORIZONTAL",
          "thumbnailImageAlignment": "LEFT",
          "title": "Your Package is on its way!",
          "description": "Did you know that you can reschedule your package delivery?",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2023/06/GENERIC-startsida-3uspar-soveraldrig-300x254.png",
          "suggestedReplies": [
            {
              "text": "Reschedule delivery",
              "postbackData": "rescheduleDelivery"
            }
          ],
          "suggestedActions": [
            {
              "text": "Track package",
              "postbackData": "trackPackage",
              "viewLocationAction": {
                "query": "United Spaces Klarabergsviadukten 63, Stockholm"
              }
            }
          ]
        }
      }'

Example 5: Vertical Rich Card featuring one suggested action and one suggested reply with additional three suggested actions below.

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567"
        ],
        "messageType": "RichCard",
        "suggestedActions": [
          {
            "text": "Find Generic",
            "postbackData": "findGeneric",
              "viewLocationAction":{
                  "query": "United Spaces Klarabergsviadukten 63, Stockholm"
              }
          },
          {
            "text": "Call Support",
            "postbackData": "callSupport",
              "dialAction":{
                  "phoneNumber": "+46701234567"
              }
          },
          {
            "text": "Visit Website",
            "postbackData": "visitWebsite",
              "openUrlAction":{
                  "url": "https://www.generic.se/"
              }
          }
        ],
        "richCardContent": {
          "height": "TALL",
          "orientation": "VERTICAL",
          "title": "Your Package is on its way!",
          "description": "Did you know that you can reschedule your package delivery?",
          "fileUrl": "https://www.generic.se/wp-content/uploads/2023/06/GENERIC-startsida-3uspar-soveraldrig-300x254.png",
          "suggestedReplies": [
            {
              "text": "Reschedule delivery",
              "postbackData": "rescheduleDelivery"
            }
          ],
          "suggestedActions": [
            {
              "text": "Track package",
              "postbackData": "trackPackage",
              "viewLocationAction": {
                "query": "United Spaces Klarabergsviadukten 63, Stockholm"
              }
            }
          ]
        }
      }'

Example 3: Vertical Rich Card featuring one suggested action and one suggested reply.


Example 4: Horizontal Rich Card featuring a left-aligned thumbnail image, one suggested action, and one suggested reply.


Example 5: Vertical Rich Card featuring one suggested action and one suggested reply with additional three suggested actions below.

Example 6: Horizontal Rich Card featuring a left-aligned thumbnail image, one suggested action, and one suggested reply.

curl -X POST https://api.genericmobile.se/Rcs/api/v1/Message \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
        "agentId": "your_agentId",
        "number": [
          "+46701234567"
        ],
        "messageType": "Carousel",
        "carouselContent": {
          "cardWidth": "MEDIUM",
          "richCardContents": [
            {
              "title": "20% Sale on DOCS!",
              "description": "Don'\''t miss out on our exclusive 20% discount on DOCS!",
              "fileUrl": "https://www.generic.se/wp-content/uploads/2022/10/GENERIC-Tjanster-GenericDocs-Page-1-1146x752-2-768x504.png",
              "suggestedActions": [
                {
                  "text": "Buy now! 🛒",
                  "postbackData": "buyNow",
                  "openUrlAction": {
                    "url": "https://www.generic.se/tjanster/docs/"
                  }
                },
                {
                  "text": "Contact us",
                  "postbackData": "contactUs",
                  "dialAction": {
                    "phoneNumber": "+46704607662"
                  }
                }
              ]
            },
            {
              "title": "Switch from SMS to Email!",
              "description": "Discover the benefits of sending your SMS as email – boost engagement and efficiency.",
              "fileUrl": "https://www.generic.se/wp-content/uploads/2019/04/GENERIC-Tjanster-meddelanden-Page-1400x1000-sms-meddelanden-till-och-fran-epost-768x549.jpg",
              "suggestedActions": [
                {
                  "text": "Learn more",
                  "postbackData": "learnMore",
                  "openUrlAction": {
                    "url": "https://www.generic.se/tjanster/sms-e-post/"
                  }
                },
                {
                  "text": "Contact us",
                  "postbackData": "contactUs",
                  "dialAction": {
                    "phoneNumber": "+46704607662"
                  }
                }
              ]
            }
          ]
        }
      }'

Example 6: Carousel featuring two rich cards, each with two suggested actions.

File Upload


curl -X POST https://api.genericmobile.se/Rcs/api/v1/UploadFile/{agentId} \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/file.png" \
  -F "additionalParam=value"


200 OK
{
    "statusCode": "OK",
    "fileId": "files/a1bcde2FGHIJKLMn3opqrs"
}

This endpoint allows you to upload a file that you can later use in RichCards or carousels. When you upload an image, you receive a fileId, which you then use in your RichCard or Carousel messages.

POST /UploadFile/{agentId}

The UploadFile endpoint is used to upload files to the RCS platform. It accepts a file via a multipart/form-data POST request along with an agentId in the route. The file is validated for allowed MIME types and must not exceed 100 MB. Uploaded files are cached for 50 days. After this period, the file will be automatically removed from our system. If you wish to continue using the image in your messages, you must re-upload it, as the associated fileId will no longer be valid once the file has been deleted.

HTTP Response

200 OK

The file was successfully uploaded, the response contains fileId to use in rich cards and status code, e.g. {statusCode: 200, "fileId": "files/a1bcde2FGHIJKLMn3opqrs"}.

400 Bad Request

Will contain a message explaining the issue, e.g. {statusCode: 400, "Message": "Unsupported file type"}

Fetch Tag Statistics

GET /Message/Tag/{tagId}

Retrieve aggregated statistics for messages linked to a specific tagId. This endpoint is useful for tracking how a tagged batch of messages performed across RCS and SMS, including delivery, reads, and replies.

Response Example

curl -X GET "https://api.genericmobile.se/Rcs/api/v1/Message/Tag/deadc0de-2bad-c4fe-feed-beefca1ff001" \
  -H "Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464"

{
  "totalNumberMessages": 3,
  "smsNumbers": 1,
  "rcsNumbers": 2,
  "deliveredSms": 1,
  "deliveredRcs": 2,
  "readRcs": 2,
  "repliedRcs": 1,
  "rcs": [
    {
      "number": "+46702345678",
      "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff002"
    },
    {
      "number": "+46701234567",
      "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff003"
    }
  ],
  "sms": [
    {
      "number": "+46701122334",
      "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff004"
    }
  ]
}

Endpoint Description

This endpoint allows you to retrieve statistics for all messages associated with a given tagId.

Tag statistics provide an overview of:

This is particularly useful for:

Path Parameter

Parameter Type Required Description
tagId GUID Yes The unique identifier of the message tag.

Response Fields

Field Type Description
totalNumberMessages int Total number of messages in the tag batch
smsNumbers int Number of SMS messages sent
rcsNumbers int Number of RCS messages sent
deliveredSms int SMS messages delivered
deliveredRcs int RCS messages delivered
readRcs int RCS messages read by recipient
repliedRcs int RCS messages with a reply
rcs array of objects Detailed info per RCS recipient
sms array of objects Detailed info per SMS recipient

Each object in rcs or sms contains:

HTTP Response

200 OK

Tag statistics successfully retrieved

Fetch Message by Message ID

GET /Message/{messageId}

Retrieve the full conversation thread associated with a specific messageId. This includes delivery status, reads, and replies if applicable. The response varies depending on whether the message was sent as RCS or SMS.

Response Example (RCS Message)

curl -X GET "https://api.genericmobile.se/Rcs/api/v1/Message/deadc0de-2bad-c4fe-feed-beefca1ff001" \
  -H "Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464"

[
  {
    "from": "+46702345678",
    "to": "Agent",
    "time": "2025-05-05T11:35:07",
    "messageType": "ACTION",
    "reply": "Call Generic"
  },
  {
    "from": "+46702345678",
    "to": "Agent",
    "time": "2025-05-05T11:35:06",
    "messageType": "READ"
  },
  {
    "from": "+46702345678",
    "to": "Agent",
    "time": "2025-05-05T11:13:07",
    "messageType": "DELIVERED"
  },
  {
    "from": "Agent",
    "to": "+46702345678",
    "time": "2025-05-05T11:13:05",
    "messageType": "TextMessage"
  }
]

Response Example (SMS Message)

curl -X GET "https://api.genericmobile.se/Rcs/api/v1/Message/deadc0de-2bad-c4fe-feed-beefca1ff001" \
  -H "Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464"

[
  {
    "from": "+46702345678",
    "to": "46701234567",
    "time": "2025-05-05T11:35:07",
    "messageType": "SMS",
    "status": "delivered"
  }
]

Endpoint Description

This endpoint returns all tracked events related to a given messageId. It supports both RCS and SMS messages. If the message is RCS, additional metadata such as delivery, read, and reply events are included. For SMS, only basic message data is returned due to limited tracking.

This is helpful for:

Path Parameter

Parameter Type Required Description
messageId GUID Yes Unique identifier of the message to fetch.

Response Fields (RCS)

Field Type Description
from string Sender number or Agent
to string Recipient number or Agent
time string Timestamp of the event (ISO 8601)
messageType string Type of message event (TextMessage, DELIVERED, READ, ACTION, NO_CAPABILITY)
reply string (optional) Reply text if applicable (for actions or replies)

HTTP Response

200 OK

Messages retrieved successfully

Notes

Fetch Messages

curl -X GET "https://api.genericmobile.se/Rcs/api/v1/Message/Agent/{agentId}?limit=100&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&phoneNumber=46701234567" \
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464'

200 OK
[
  {
        "agentId": "your_agentId",
        "time": "2025-03-11T14:19:51",
        "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff00d",
        "messageType": "ACTION",
        "to": "Generic",
        "postbackData": "visitGeneric",
        "from": "+46701234567",
        "response": "Visit Generic"
    },
    {
        "agentId": "your_agentId",
        "time": "2025-03-11T14:20:36",
        "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff00d",
        "messageType": "READ",
        "to": "Generic",
        "from": "+46701234567"
    },
    {
        "agentId": "your_agentId",
        "time": "2025-03-11T14:20:36",
        "messageId": "deadc0de-2bad-c4fe-feed-beefca1ff00d",
        "messageType": "DELIVERED",
        "to": "Generic",
        "from": "+46701234567"
    }
]

GET /Message/Agent/{agentId}

This endpoint allows an RCS agent to retrieve messages associated with a specific agent ID. It supports optional filters such as message limits, time range, and phone number filtering. The response will contain messages that match the specified criteria or indicate if no messages are found.

This can be useful for: - Checking recent messages sent/received by an agent. - Filtering messages within a specific timeframe. - Retrieving messages exchanged with a specific phone number.

How to Use:

To use this endpoint, send a GET request to: https://api.genericmobile.se/Rcs/api/v1/Message/Agent/{agentId}

Replace {agentId} with the actual ID of the agent whose messages you want to retrieve. You can also include optional query parameters to filter results based on your needs.

For example, if you want to retrieve messages for agent ID 12345, with a limit of 50 messages between March 1 and March 17, 2025, for phone number 46701234567, your request would look like this:

GET https://api.genericmobile.se/Rcs/api/v1/Message/Agent/12345?limit=50&startTime=2025-03-01T00:00:00Z&endTime=2025-03-17T23:59:59Z&phoneNumber=46701234567

Query Parameters

Parameter Required Type Description Default
limit No int The maximum number of messages to return. 100
startTime No string The start date/time for message retrieval (ISO 8601 format). null
endTime No string The end date/time for message retrieval (ISO 8601 format). null
phoneNumber No string Filter messages by a specific phone number (E.164 format). null

Capability

GET /Capability/{agentId}

curl -X GET https://api.genericmobile.se/Rcs/api/v1/Capability/{agentId}\
  -H 'Authorization: Bearer 90be0b2c-b218-4070-a890-152821090464' \
  -H 'Content-Type: application/json' \
  -d '{
       "+46701234567"
      }'

200 OK
{
  true
}

This endpoint allows you to check whether a given phone number has access to Rich Communication Services (RCS). It returns true if the number supports RCS and false otherwise.

Note: A capability check is automatically performed for each message sent via the POST /Message endpoint. This means you do not need to manually verify if a number supports RCS before sending a message. The capability endpoint is provided only for optional, manual checks of specific numbers and is not required for sending RCS messages.

Error Handling and Response Codes

The RCS API uses standard HTTP status codes to indicate success or failure of requests. Your application should handle different response codes appropriately. Below is a summary of expected response codes and their meanings, as well as how error information is returned:

Success Responses

Code Status Description
200 OK The request was successful. For GET requests, the response body contains the requested data (e.g., a delivery report).
201 Created The request was successful and a new resource was created. For message send requests, this means the message was accepted for delivery. The response will include a MessageId (or multiple IDs).
204 No Content The request was successful but there is no content in the response.

Client Error Responses

Code Status Description
400 Bad Request The request was invalid or missing required parameters. The response body will include details. (e.g., a phone number is improperly formatted, or a field is omitted.)
401 Unauthorized Authentication failed. The API key or credentials provided are incorrect, expired, or do not have access to the API.
403 Forbidden The request was understood but refused, typically due to insufficient privileges or disabled features.
404 Not Found The requested resource was not found. (Wrong endpoint or MessageId doesn't exist or doesn't belong to your account.)
405 Method Not Allowed The HTTP method used is not supported for this endpoint.
406 Not Acceptable The client requested a format not supported by the server.
415 Unsupported Media Type The request's content type is not supported (e.g., missing Content-Type: application/json).
429 Too Many Requests You have hit the rate limit for requests. The server is throttling requests. The response may include a Retry-After header indicating how long to wait.

Server Error Responses

Code Status Description
500 Internal Server Error An unexpected error occurred on the server side. The request may be valid, but the server couldn't process it due to an internal issue.
502 Bad Gateway The server received an invalid response from an upstream service (temporary network issue, etc.).
503 Service Unavailable The server is currently unavailable (maintenance or overload). Retry later.
504 Gateway Timeout The server, acting as a gateway, did not receive a timely response from an upstream service.
shell