---
updatedAt: 2026-04-21T05:49:16.000Z
agentTools:
  projectIndex: https://developers.kudosity.com/llms.txt
---

# Send RCS message

This endpoint is in beta and may change in future versions.
Sends an RCS message to a single recipient.

The message can be text (`content_type: text`) or a single image or video (`content_type: media`).
For media, we fetch the start of the file when you send the request, which can add up to 10 seconds.
The request fails with `400` if the file isn't publicly reachable over `https`, redirects, doesn't
respond in time, or has an unsupported, mismatched or oversized file type. Each problem is reported
against `content.media.file_url`.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Transmit Message API",
    "description": "Transmit APIs",
    "version": "20250101"
  },
  "servers": [
    {
      "url": "https://api.transmitmessage.com"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v2/rcs/messages": {
      "post": {
        "tags": [
          "RCS"
        ],
        "summary": "Send RCS message",
        "description": "This endpoint is in beta and may change in future versions.\nSends an RCS message to a single recipient.\n\nThe message can be text (`content_type: text`) or a single image or video (`content_type: media`).\nFor media, we fetch the start of the file when you send the request, which can add up to 10 seconds.\nThe request fails with `400` if the file isn't publicly reachable over `https`, redirects, doesn't\nrespond in time, or has an unsupported, mismatched or oversized file type. Each problem is reported\nagainst `content.media.file_url`.\n",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RcsRequest"
              },
              "examples": {
                "text": {
                  "summary": "Text message",
                  "value": {
                    "sender": "DemoSender",
                    "recipient": "447903749662",
                    "content_type": "text",
                    "content": {
                      "text": {
                        "message": "Hi Michael,\nJust a quick reminder. You are amazing!!\nReply STOP to opt out."
                      }
                    },
                    "message_ref": "order-12345"
                  }
                },
                "media": {
                  "summary": "Image or video message",
                  "value": {
                    "sender": "DemoSender",
                    "recipient": "447903749662",
                    "content_type": "media",
                    "content": {
                      "media": {
                        "file_url": "https://cdn.example.com/promo/spring-sale.jpg"
                      }
                    },
                    "sms_fallback": {
                      "message": "Our spring sale is on! https://cdn.example.com/promo/spring-sale.jpg"
                    },
                    "message_ref": "order-12346"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/RCSSuccessResponse"
          },
          "400": {
            "$ref": "#/components/responses/InputValidationResponse"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedErrorResponse"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CommonResponseMeta": {
        "type": "object",
        "properties": {
          "request": {
            "type": "object",
            "description": "Optional metadata (e.g. requestId, traceId)"
          },
          "meta": {
            "type": "object",
            "description": "Optional pagination, feature flags, etc."
          }
        }
      },
      "CommonSuccessResponse": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "description": "Success response payload"
              }
            },
            "required": [
              "data"
            ]
          },
          {
            "$ref": "#/components/schemas/CommonResponseMeta"
          }
        ]
      },
      "Uri": {
        "type": "string",
        "description": "string providing an URI formatted according to IETF RFC 3986.",
        "format": "uri"
      },
      "ProblemDetails": {
        "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n",
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/Uri"
          },
          "title": {
            "type": "string",
            "description": "A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized)."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem"
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code corresponding to this error."
          }
        },
        "required": [
          "type",
          "title",
          "detail",
          "status"
        ],
        "example": {
          "type": "https://developers.kudosity.com/reference/errors",
          "title": "Description of the type of problem that occurred",
          "detail": "Description of specific occurrence of the problem",
          "status": 400
        }
      },
      "CommonErrorResponse": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "error": {
                "$ref": "#/components/schemas/ProblemDetails"
              }
            },
            "required": [
              "error"
            ]
          },
          {
            "$ref": "#/components/schemas/CommonResponseMeta"
          }
        ]
      },
      "InputValidationIssue": {
        "type": "object",
        "description": "An issue detected during input validation.\n",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the param or field that failed validation."
          },
          "code": {
            "type": "integer",
            "description": "The internal api specific error code."
          },
          "message": {
            "description": "The error message",
            "type": "string"
          }
        }
      },
      "InputValidationProblem": {
        "description": "HTTP 400 Bad Request - The request failed validation.\n\nThe `issues` array lists the problems found with the request. Some endpoints stop at the first problem, so fix it and retry to find any others. Each issue has a `message`, and usually the `name` of the parameter or field.\n",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProblemDetails"
          },
          {
            "properties": {
              "issues": {
                "description": "An array of issues detected during input validation.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/InputValidationIssue"
                }
              }
            }
          }
        ],
        "example": {
          "type": "https://developers.kudosity.com/reference/errors#input-validation",
          "title": "Invalid Request",
          "detail": "Request validation failed",
          "status": 400,
          "issues": [
            {
              "name": "field_name",
              "message": "field_name is required"
            }
          ]
        }
      },
      "UnauthorizedProblem": {
        "description": "HTTP 401 Unauthorized - API authentication failed.\n\nThe request was rejected because the API key is missing, invalid, expired, or lacks sufficient permissions for this resource. Check your Authorization header and API key configuration.\n",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        ],
        "example": {
          "type": "https://developers.kudosity.com/reference/errors#unauthorized",
          "title": "API Authentication Failed",
          "detail": "Missing or invalid API key in Authorization header. Verify your API key is correct and has the required permissions",
          "status": 401
        }
      },
      "InternalServerErrorProblem": {
        "description": "HTTP 500 Internal Server Error - The API encountered an unexpected error.\n\nThis error isn't caused by your request. You can retry a GET request later. Before you retry a POST, PATCH or DELETE request, check the resource's current state, because the request may already have been applied. Contact support if the error continues.\n",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        ],
        "example": {
          "type": "https://developers.kudosity.com/reference/errors#server-error",
          "title": "Internal Server Error",
          "detail": "The server encountered an unexpected error",
          "status": 500
        }
      },
      "RCSText": {
        "type": "object",
        "description": "Text content for the message.",
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 3072,
            "description": "The text message body.\n\n**Message Types:**\n- **Basic RCS Messages**: Up to 160 characters (SMS format in RCS)\n- **Simple RCS Messages**: Up to 3072 characters with emoji and UTF-8 support\n"
          }
        },
        "required": [
          "message"
        ]
      },
      "RCSTextContent": {
        "type": "object",
        "properties": {
          "text": {
            "$ref": "#/components/schemas/RCSText"
          }
        },
        "required": [
          "text"
        ]
      },
      "RcsMedia": {
        "type": "object",
        "description": "A single image or video, delivered as an RCS file message.\n\nMedia messages don't currently support a caption.\n",
        "properties": {
          "file_url": {
            "type": "string",
            "format": "uri",
            "description": "Public URL of the image or video to send.\n\n- Must be an absolute `https://` URL of up to 2,048 characters, on the default port (443), without credentials.\n- Spaces and non-ASCII characters must be percent-encoded.\n- Must be publicly reachable, return the file directly and respond within 10 seconds. Redirects are not followed.\n- Your server must return a `Content-Type` header matching one of the supported types, and the file content must match it:\n  - Images: `image/jpeg`, `image/png`, `image/gif`\n  - Videos: `video/mp4`, `video/mpeg`, `video/mpeg4`, `video/m4v`, `video/webm`, `video/h263`\n- Maximum file size is 100 MB. Return a `Content-Length` or `Content-Range` header so the size can be checked.\n\nRCS providers cache files by URL for up to 60 days. To change a file, host it at a new URL.\n"
          }
        },
        "required": [
          "file_url"
        ],
        "example": {
          "file_url": "https://cdn.example.com/promo/spring-sale.jpg"
        }
      },
      "RcsMediaContent": {
        "type": "object",
        "properties": {
          "media": {
            "$ref": "#/components/schemas/RcsMedia"
          }
        },
        "required": [
          "media"
        ]
      },
      "RCSSMSFallback": {
        "type": "object",
        "description": "Provides intelligent fallback for non-RCS capable devices and carrier delivery issues. If the RCS message fails, the SMS will send the configured message to the recipient instead.\n",
        "properties": {
          "sender": {
            "type": "string",
            "description": "The sender number to use for SMS fallback, which can be in [E.164](http://en.wikipedia.org/wiki/E.164) international format or an alphanumeric sender ID."
          },
          "message": {
            "type": "string",
            "description": "The message to send through SMS. SMS messages are subject to certain character limitations, please read our SMS documentation for details."
          }
        },
        "required": [
          "message"
        ]
      },
      "RcsRequest": {
        "type": "object",
        "properties": {
          "sender": {
            "type": "string",
            "description": "The RCS agent ID assigned to your registered agent.\n\nUnlike SMS, WhatsApp, and MMS, RCS messages do not come from a phone number.\nThey are always sent through an agent.\n\n- Must be a registered RCS agent identifier.\n- Example: `DemoSender`\n- Can be alphanumeric or numeric.\n"
          },
          "recipient": {
            "type": "string",
            "format": "phone",
            "description": "The destination number for delivery.\nCan be either in local format or in international format.\nFor international format, it should follow the [E.164 standard](http://en.wikipedia.org/wiki/E.164).\n\nExamples of conversions to E.164 format:\n- Australia: 0438 333 061 → 61438333061\n- UK: 07123 456 789 → 447123456789\n"
          },
          "content_type": {
            "type": "string",
            "description": "Type of the message content. Must match the key used in `content`.\n- `text` — a text message, sent in `content.text`\n- `media` — a single image or video, sent in `content.media`\n",
            "enum": [
              "text",
              "media"
            ]
          },
          "content": {
            "type": "object",
            "description": "The message content to be sent.\n\n- `text`: supports both Basic RCS messages (160 characters) and Simple RCS messages (3072 characters), with UTF-8 and emoji support.\n- `media`: one image or video by public URL, without a caption.\n",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RCSTextContent"
              },
              {
                "$ref": "#/components/schemas/RcsMediaContent"
              }
            ]
          },
          "sms_fallback": {
            "$ref": "#/components/schemas/RCSSMSFallback"
          },
          "message_ref": {
            "type": "string",
            "description": "A reference supplied by your system. Maximum length of 500 characters.\n\nThis reference is included in webhook events so you can relate events with the original message.\n\nFor example, being able to relate a Link Hit event to a specific sent message.\n"
          }
        },
        "required": [
          "sender",
          "recipient",
          "content_type",
          "content"
        ],
        "example": {
          "sender": "DemoSender",
          "recipient": "447903749662",
          "content_type": "text",
          "content": {
            "text": {
              "message": "Hi Michael,\nJust a quick reminder. You are amazing!!\nReply STOP to opt out."
            }
          },
          "message_ref": "order-12345"
        }
      },
      "RcsResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the message."
          },
          "message_ref": {
            "type": "string",
            "description": "Optional reference ID set by the user for the message."
          },
          "sender": {
            "type": "string",
            "description": "Registered RCS Agent ID."
          },
          "recipient": {
            "type": "string",
            "description": "Recipient phone number in international format."
          },
          "content_type": {
            "type": "string",
            "description": "Type of the message content. More content types may be added; ignore values you don't recognise.\n- `text` — a text message\n- `media` — a single image or video\n",
            "enum": [
              "text",
              "media"
            ]
          },
          "content": {
            "type": "object",
            "description": "Content of the message.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RCSTextContent"
              },
              {
                "$ref": "#/components/schemas/RcsMediaContent"
              }
            ]
          },
          "sms_fallback": {
            "$ref": "#/components/schemas/RCSSMSFallback"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server."
          }
        },
        "required": [
          "id",
          "sender",
          "recipient",
          "content_type",
          "content",
          "created_at"
        ],
        "example": {
          "id": "6fdae71c-dad7-4c36-9734-a69693ecf3b4",
          "message_ref": "order-12345",
          "sender": "DemoSender",
          "recipient": "447903749662",
          "content_type": "text",
          "content": {
            "text": {
              "message": "Hi Michael,\nJust a quick reminder. You are amazing!!\nReply STOP to opt out."
            }
          },
          "created_at": "2021-01-01T00:00:00Z"
        }
      }
    },
    "responses": {
      "InputValidationResponse": {
        "description": "Input Validation Error",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/CommonErrorResponse"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/InputValidationProblem"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "UnauthorizedErrorResponse": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/CommonErrorResponse"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/UnauthorizedProblem"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "InternalServerErrorResponse": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/CommonErrorResponse"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "$ref": "#/components/schemas/InternalServerErrorProblem"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "RCSSuccessResponse": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/CommonSuccessResponse"
                },
                {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RcsResponse"
                    }
                  }
                }
              ]
            },
            "example": {
              "data": {
                "id": "6fdae71c-dad7-4c36-9734-a69693ecf3b4",
                "message_ref": "order-12345",
                "sender": "DemoSender",
                "recipient": "447903749662",
                "content_type": "text",
                "content": {
                  "text": {
                    "message": "Hi Michael,\nJust a quick reminder. You are amazing!!\nReply STOP to opt out."
                  }
                },
                "created_at": "2021-01-01T00:00:00Z"
              },
              "request": {},
              "meta": {}
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "All API requests require your API credentials, you will find them once logged into your account on the SETTINGS page. Scroll down to API Settings to find your API key.\n"
      }
    }
  }
}
```