# Send a Message

POST https://api.smobi.com/v1/message

Authentication: x-api-key header (brand-scoped API key).

Send an SMS or RCS message to a customer. Include SMS content alongside RCS to provide a fallback when RCS is unavailable.

## Operation

```json
{
  "operationId": "sendMessage",
  "parameters": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SendMessage"
        },
        "examples": {
          "sms-text": {
            "summary": "SMS Text",
            "value": {
              "clientRef": "order-123",
              "recipientPhoneNumber": "15552223333",
              "content": {
                "sms": {
                  "content": "Your order is on its way."
                }
              }
            }
          },
          "rcs-text": {
            "summary": "RCS Text with SMS Fallback",
            "value": {
              "clientRef": "order-123",
              "recipientPhoneNumber": "15552223333",
              "content": {
                "rcs": {
                  "content": {
                    "type": "TEXT",
                    "content": "Your order is on its way."
                  }
                },
                "sms": {
                  "content": "Your order is on its way."
                }
              }
            }
          },
          "rich-card": {
            "summary": "Rich Card",
            "value": {
              "clientRef": "order-123",
              "recipientPhoneNumber": "15552223333",
              "content": {
                "rcs": {
                  "content": {
                    "type": "RICH_CARD",
                    "item": {
                      "title": "Your Order Is on Its Way",
                      "description": "Track your delivery for the latest updates."
                    }
                  }
                }
              }
            }
          },
          "send-rich-card": {
            "summary": "Send Rich Card Message",
            "description": "Example of sending a rich card message with both RCS and SMS fallback",
            "value": {
              "clientRef": "61efac14-961c-4070-a369-04e16578e86f",
              "recipientPhoneNumber": "15552223333",
              "content": {
                "rcs": {
                  "content": {
                    "type": "RICH_CARD",
                    "item": {
                      "title": "Blue Cotton T-Shirt",
                      "description": "Premium comfort with style. Available in S-XL sizes.",
                      "mediaUrl": "https://smobi-public-templates.s3.us-east-1.amazonaws.com/public/products/Product7.png",
                      "orientation": "VERTICAL",
                      "thumbnailPosition": "RIGHT",
                      "height": "SHORT",
                      "localSuggestions": []
                    },
                    "globalSuggestions": [
                      {
                        "id": "reply-1",
                        "text": "Reply to message",
                        "type": "REPLY"
                      },
                      {
                        "id": "url-1",
                        "text": "Visit our website",
                        "type": "OPEN_URL",
                        "url": "https://example.com"
                      },
                      {
                        "id": "phone-1",
                        "text": "Call support",
                        "type": "DIAL_PHONE",
                        "phoneNumber": "+12223334444"
                      },
                      {
                        "id": "location-1",
                        "text": "Show location",
                        "type": "SHOW_LOCATION",
                        "latitude": "37.7749",
                        "longitude": "-122.4194",
                        "label": "San Francisco"
                      }
                    ]
                  }
                },
                "sms": {
                  "content": "Check out our Blue Cotton T-Shirt! View it here: https://example.com/products/blue-tshirt. Need help? Reply to this message.",
                  "mediaUrl": "https://smobi-public-templates.s3.us-east-1.amazonaws.com/public/products/Product7.png"
                }
              }
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Message accepted for processing. Delivery is reported asynchronously through status webhooks.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SendMessageResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad Request - Invalid request parameters",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Invalid phone number"
              },
              "error": {
                "type": "string",
                "example": "Bad Request"
              },
              "statusCode": {
                "type": "number",
                "example": 400
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - Invalid API key",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Invalid API key"
              },
              "error": {
                "type": "string",
                "example": "Unauthorized"
              },
              "statusCode": {
                "type": "number",
                "example": 401
              }
            }
          }
        }
      }
    }
  },
  "summary": "Send a Message",
  "tags": [
    "Messaging"
  ],
  "security": [
    {
      "x-api-key": []
    }
  ],
  "description": "Send an SMS or RCS message to a customer. Include SMS content alongside RCS to provide a fallback when RCS is unavailable."
}
```

## Referenced Schemas

```json
{
  "SendMessage": {
    "type": "object",
    "properties": {
      "clientRef": {
        "type": "string",
        "description": "Client reference ID",
        "example": "client-ref-123"
      },
      "recipientPhoneNumber": {
        "type": "string",
        "description": "Recipient phone number, string of all digits, for example, 12223334444",
        "example": "15552223333"
      },
      "content": {
        "description": "Message content",
        "example": {
          "rcs": {
            "content": {
              "type": "TEXT",
              "content": "Hello, world!",
              "globalSuggestions": [
                {
                  "type": "REPLY",
                  "text": "Reply",
                  "id": "reply-1"
                }
              ]
            }
          },
          "sms": {
            "content": "Check out this image!",
            "mediaUrl": "https://example.com/image.jpg"
          }
        },
        "allOf": [
          {
            "$ref": "#/components/schemas/RenderedTemplateContent"
          }
        ]
      }
    },
    "required": [
      "clientRef",
      "recipientPhoneNumber",
      "content"
    ]
  },
  "RenderedTemplateContent": {
    "type": "object",
    "properties": {
      "rcs": {
        "description": "Rendered RCS content, used if RCS is supported by the recipientPhoneNumber.",
        "allOf": [
          {
            "$ref": "#/components/schemas/RcsContent"
          }
        ]
      },
      "sms": {
        "description": "SMS text or media, also used as an RCS fallback. Provide non-empty text, a media URL, or both. Select a variant to inspect its required fields.",
        "allOf": [
          {
            "$ref": "#/components/schemas/SmsContent"
          }
        ]
      }
    },
    "required": [],
    "additionalProperties": false,
    "description": "Message content for RCS, SMS, or both. Supply content for at least one configured channel. RCS is not required for SMS-only messages."
  },
  "RcsContent": {
    "type": "object",
    "properties": {
      "content": {
        "description": "Rendered RCS message content",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextMessage"
          },
          {
            "$ref": "#/components/schemas/ContentMessage"
          },
          {
            "$ref": "#/components/schemas/RichCardMessage"
          },
          {
            "$ref": "#/components/schemas/CarouselMessage"
          }
        ]
      }
    },
    "required": [
      "content"
    ]
  },
  "TextMessage": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "TEXT"
        ],
        "description": "Type of message"
      },
      "globalSuggestions": {
        "type": "array",
        "description": "Global suggestions associated with the message. Limit 11 suggestions, max 25 characters each.",
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/ReplyAction"
            },
            {
              "$ref": "#/components/schemas/OpenUrlAction"
            },
            {
              "$ref": "#/components/schemas/DialPhoneAction"
            },
            {
              "$ref": "#/components/schemas/ShowLocationAction"
            },
            {
              "$ref": "#/components/schemas/RequestLocationAction"
            },
            {
              "$ref": "#/components/schemas/CalendarEventAction"
            }
          ],
          "discriminator": {
            "propertyName": "type",
            "mapping": {
              "REPLY": "#/components/schemas/ReplyAction",
              "OPEN_URL": "#/components/schemas/OpenUrlAction",
              "DIAL_PHONE": "#/components/schemas/DialPhoneAction",
              "SHOW_LOCATION": "#/components/schemas/ShowLocationAction",
              "REQUEST_LOCATION": "#/components/schemas/RequestLocationAction",
              "CALENDAR_EVENT": "#/components/schemas/CalendarEventAction"
            }
          }
        },
        "maxItems": 11
      },
      "content": {
        "type": "string",
        "description": "Text content of the message",
        "minLength": 1
      }
    },
    "required": [
      "type",
      "content"
    ]
  },
  "ReplyAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "REPLY"
        ],
        "description": "Type of action"
      }
    },
    "required": [
      "id",
      "text",
      "type"
    ]
  },
  "OpenUrlAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "OPEN_URL"
        ],
        "description": "Type of action"
      },
      "url": {
        "type": "string",
        "description": "The publicly accessible URL to open, for example, https://www.example.com"
      }
    },
    "required": [
      "id",
      "text",
      "type",
      "url"
    ]
  },
  "DialPhoneAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "DIAL_PHONE"
        ],
        "description": "Type of action"
      },
      "phoneNumber": {
        "type": "string",
        "description": "The phone number in E.164 format, for example, +12223334444"
      }
    },
    "required": [
      "id",
      "text",
      "type",
      "phoneNumber"
    ]
  },
  "ShowLocationAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "SHOW_LOCATION"
        ],
        "description": "Type of action"
      },
      "latitude": {
        "type": "string",
        "description": "The latitude in degrees. It must be in the range [-90.0, +90.0]."
      },
      "longitude": {
        "type": "string",
        "description": "The longitude in degrees. It must be in the range [-180.0, +180.0]."
      },
      "label": {
        "type": "string",
        "description": "The label of the location, for example, \"Home\", \"Work\", \"School\", etc."
      }
    },
    "required": [
      "id",
      "text",
      "type",
      "latitude",
      "longitude"
    ]
  },
  "RequestLocationAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "REQUEST_LOCATION"
        ],
        "description": "Type of action"
      }
    },
    "required": [
      "id",
      "text",
      "type"
    ]
  },
  "CalendarEventAction": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique identifier for the action",
        "minLength": 1
      },
      "text": {
        "type": "string",
        "description": "Text to display for the action, Maximum 25 characters",
        "minLength": 1,
        "maxLength": 25
      },
      "type": {
        "type": "string",
        "enum": [
          "CALENDAR_EVENT"
        ],
        "description": "Type of action"
      },
      "eventTitle": {
        "type": "string",
        "description": "Event title. Maximum 100 characters"
      },
      "eventDescription": {
        "type": "string",
        "description": "Event description. Maximum 500 characters"
      },
      "startDate": {
        "format": "date-time",
        "type": "string",
        "description": "The start date of the event, in RFC 3339 format"
      },
      "endDate": {
        "format": "date-time",
        "type": "string",
        "description": "The end date of the event, in RFC 3339 format"
      }
    },
    "required": [
      "id",
      "text",
      "type",
      "eventTitle",
      "startDate",
      "endDate"
    ]
  },
  "ContentMessage": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "CONTENT"
        ],
        "description": "Type of message"
      },
      "globalSuggestions": {
        "type": "array",
        "description": "Global suggestions associated with the message. Limit 11 suggestions, max 25 characters each.",
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/ReplyAction"
            },
            {
              "$ref": "#/components/schemas/OpenUrlAction"
            },
            {
              "$ref": "#/components/schemas/DialPhoneAction"
            },
            {
              "$ref": "#/components/schemas/ShowLocationAction"
            },
            {
              "$ref": "#/components/schemas/RequestLocationAction"
            },
            {
              "$ref": "#/components/schemas/CalendarEventAction"
            }
          ],
          "discriminator": {
            "propertyName": "type",
            "mapping": {
              "REPLY": "#/components/schemas/ReplyAction",
              "OPEN_URL": "#/components/schemas/OpenUrlAction",
              "DIAL_PHONE": "#/components/schemas/DialPhoneAction",
              "SHOW_LOCATION": "#/components/schemas/ShowLocationAction",
              "REQUEST_LOCATION": "#/components/schemas/RequestLocationAction",
              "CALENDAR_EVENT": "#/components/schemas/CalendarEventAction"
            }
          }
        },
        "maxItems": 11
      },
      "contentUrl": {
        "type": "string",
        "description": "The publicly accessible URL of the file, for example, https://www.example.com/content.jpg",
        "minLength": 1
      }
    },
    "required": [
      "type",
      "contentUrl"
    ]
  },
  "RichCardMessage": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "RICH_CARD"
        ],
        "description": "Type of message"
      },
      "globalSuggestions": {
        "type": "array",
        "description": "Global suggestions associated with the message. Limit 11 suggestions, max 25 characters each.",
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/ReplyAction"
            },
            {
              "$ref": "#/components/schemas/OpenUrlAction"
            },
            {
              "$ref": "#/components/schemas/DialPhoneAction"
            },
            {
              "$ref": "#/components/schemas/ShowLocationAction"
            },
            {
              "$ref": "#/components/schemas/RequestLocationAction"
            },
            {
              "$ref": "#/components/schemas/CalendarEventAction"
            }
          ],
          "discriminator": {
            "propertyName": "type",
            "mapping": {
              "REPLY": "#/components/schemas/ReplyAction",
              "OPEN_URL": "#/components/schemas/OpenUrlAction",
              "DIAL_PHONE": "#/components/schemas/DialPhoneAction",
              "SHOW_LOCATION": "#/components/schemas/ShowLocationAction",
              "REQUEST_LOCATION": "#/components/schemas/RequestLocationAction",
              "CALENDAR_EVENT": "#/components/schemas/CalendarEventAction"
            }
          }
        },
        "maxItems": 11
      },
      "item": {
        "description": "Rich card content",
        "allOf": [
          {
            "$ref": "#/components/schemas/RichCardBaseMessage"
          }
        ]
      }
    },
    "required": [
      "type",
      "item"
    ]
  },
  "RichCardBaseMessage": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Title of the rich card, Maximum 200 characters",
        "minLength": 1
      },
      "description": {
        "type": "string",
        "description": "Description of the rich card, Maximum 2000 characters"
      },
      "mediaUrl": {
        "type": "string",
        "description": "The publicly accessible URL of the image attachment. Supported types are .jpg, .jpeg, and .png"
      },
      "orientation": {
        "type": "string",
        "enum": [
          "VERTICAL",
          "HORIZONTAL"
        ],
        "description": "Orientation of the rich card"
      },
      "thumbnailPosition": {
        "type": "string",
        "enum": [
          "LEFT",
          "RIGHT"
        ],
        "description": "Position of the thumbnail"
      },
      "height": {
        "type": "string",
        "enum": [
          "SHORT",
          "MEDIUM",
          "TALL"
        ],
        "description": "Height of the rich card"
      },
      "localSuggestions": {
        "type": "array",
        "description": "Local suggestions associated with the rich card. Limit 4 suggestions, max 25 characters each.",
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/ReplyAction"
            },
            {
              "$ref": "#/components/schemas/OpenUrlAction"
            },
            {
              "$ref": "#/components/schemas/DialPhoneAction"
            },
            {
              "$ref": "#/components/schemas/ShowLocationAction"
            },
            {
              "$ref": "#/components/schemas/RequestLocationAction"
            },
            {
              "$ref": "#/components/schemas/CalendarEventAction"
            }
          ],
          "discriminator": {
            "propertyName": "type",
            "mapping": {
              "REPLY": "#/components/schemas/ReplyAction",
              "OPEN_URL": "#/components/schemas/OpenUrlAction",
              "DIAL_PHONE": "#/components/schemas/DialPhoneAction",
              "SHOW_LOCATION": "#/components/schemas/ShowLocationAction",
              "REQUEST_LOCATION": "#/components/schemas/RequestLocationAction",
              "CALENDAR_EVENT": "#/components/schemas/CalendarEventAction"
            }
          }
        },
        "maxItems": 4
      }
    },
    "required": [
      "title"
    ]
  },
  "CarouselMessage": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "CAROUSEL"
        ],
        "description": "Type of message"
      },
      "globalSuggestions": {
        "type": "array",
        "description": "Global suggestions associated with the message. Limit 11 suggestions, max 25 characters each.",
        "items": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/ReplyAction"
            },
            {
              "$ref": "#/components/schemas/OpenUrlAction"
            },
            {
              "$ref": "#/components/schemas/DialPhoneAction"
            },
            {
              "$ref": "#/components/schemas/ShowLocationAction"
            },
            {
              "$ref": "#/components/schemas/RequestLocationAction"
            },
            {
              "$ref": "#/components/schemas/CalendarEventAction"
            }
          ],
          "discriminator": {
            "propertyName": "type",
            "mapping": {
              "REPLY": "#/components/schemas/ReplyAction",
              "OPEN_URL": "#/components/schemas/OpenUrlAction",
              "DIAL_PHONE": "#/components/schemas/DialPhoneAction",
              "SHOW_LOCATION": "#/components/schemas/ShowLocationAction",
              "REQUEST_LOCATION": "#/components/schemas/RequestLocationAction",
              "CALENDAR_EVENT": "#/components/schemas/CalendarEventAction"
            }
          }
        },
        "maxItems": 11
      },
      "width": {
        "type": "string",
        "enum": [
          "SMALL",
          "MEDIUM"
        ],
        "description": "Width of the carousel"
      },
      "items": {
        "type": "array",
        "description": "Items in the carousel",
        "items": {
          "$ref": "#/components/schemas/RichCardBaseMessage"
        },
        "minItems": 2,
        "maxItems": 10
      }
    },
    "required": [
      "type",
      "width",
      "items"
    ]
  },
  "SmsContent": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "Content of the SMS message. Optional if mediaUrl is provided (content becomes caption).",
        "example": "Hello, this is your message text",
        "minLength": 1
      },
      "mediaUrl": {
        "type": "string",
        "description": "Optional media URL. When provided, content becomes the caption for the media.",
        "example": "https://example.com/image.jpg"
      }
    },
    "description": "Provide non-empty text content, a media URL, or both. When media is supplied, text is the caption.",
    "anyOf": [
      {
        "title": "SMS Text",
        "required": [
          "content"
        ]
      },
      {
        "title": "SMS Media",
        "required": [
          "mediaUrl"
        ],
        "properties": {
          "mediaUrl": {
            "minLength": 1
          }
        }
      }
    ]
  },
  "SendMessageResponse": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "Status of the message processing",
        "example": "PROCESSING"
      },
      "smobiMessageId": {
        "type": "string",
        "description": "Unique identifier for the message in Smobi system",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      }
    },
    "required": [
      "status",
      "smobiMessageId"
    ]
  }
}
```