# Inbound Message Payload

Inbound V2 events contain customer replies and interactions. Inspect `channel` and the message subtype before reading the SMS or RCS content.

Smobi sends these events to your configured HTTPS receiver. [Configure Webhooks](/docs/guides/webhooks) before processing events.

## Example Payloads

### SMS Text Message

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "to": "15552223333",
  "from": "15551234567",
  "channel": "SMS",
  "timestamp": "2021-01-01T00:00:00.000Z",
  "sms": {
    "content": "Hello, world!"
  }
}
```

### SMS with Media

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "to": "15552223333",
  "from": "15551234567",
  "channel": "SMS",
  "timestamp": "2021-01-01T00:00:00.000Z",
  "sms": {
    "content": "",
    "downloadUrl": "https://example.com/image.jpg",
    "fileExtension": "jpg"
  }
}
```

### RCS Text Message

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "to": "15552223333",
  "from": "15551234567",
  "channel": "RCS",
  "timestamp": "2021-01-01T00:00:00.000Z",
  "rcs": {
    "type": "TEXT",
    "content": "Hello from RCS!"
  }
}
```

### RCS Suggestion Interaction

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "to": "15552223333",
  "from": "15551234567",
  "channel": "RCS",
  "timestamp": "2021-01-01T00:00:00.000Z",
  "rcs": {
    "type": "SUGGESTION",
    "content": {
      "parentSmobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
      "parentClientRef": "client-ref-123",
      "suggestionId": "suggestion-123",
      "text": "Yes, I agree"
    }
  }
}
```

## Receiver Requirements

- Validate the authentication headers configured for your receiver.
- Persist or enqueue each accepted event before returning a successful `2xx` response.
- Handle repeated events and out-of-order status updates.

## Payload Contract

The following contract and referenced schemas describe the JSON body sent to your receiver. These are outbound events, not endpoints on `api.smobi.com`. [Download Webhook Schemas](/webhook-payloads.json).

```json
{
  "$ref": "#/components/schemas/BaseOutboundMessageV2"
}
```

## Referenced Schemas

```json
{
  "BaseOutboundMessageV2": {
    "type": "object",
    "properties": {
      "smobiMessageId": {
        "type": "string",
        "description": "The reference number of the message in the Smobi system",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      },
      "to": {
        "type": "string",
        "description": "The phone number of the recipient",
        "example": "15552223333"
      },
      "from": {
        "type": "string",
        "description": "The phone number of the sender",
        "example": "15551234567"
      },
      "channel": {
        "type": "string",
        "description": "The channel of the message - indicates which payload field to access",
        "enum": [
          "SMS",
          "RCS"
        ],
        "example": "SMS"
      },
      "timestamp": {
        "type": "string",
        "description": "The timestamp of the message",
        "example": "2021-01-01T00:00:00.000Z"
      },
      "sms": {
        "description": "SMS message content (present when channel is SMS)",
        "allOf": [
          {
            "$ref": "#/components/schemas/SmobiOutboundSmsMessageContentV2"
          }
        ]
      },
      "rcs": {
        "description": "RCS message content (present when channel is RCS)",
        "oneOf": [
          {
            "$ref": "#/components/schemas/SmobiTextMessageContentV2",
            "title": "Text"
          },
          {
            "$ref": "#/components/schemas/SmobiContentMessageContentV2",
            "title": "Content"
          },
          {
            "$ref": "#/components/schemas/SmobiLocationMessageContentV2",
            "title": "Location"
          },
          {
            "$ref": "#/components/schemas/SmobiSuggestionMessageContentV2",
            "title": "Suggestion"
          }
        ]
      }
    },
    "required": [
      "smobiMessageId",
      "to",
      "from",
      "channel",
      "timestamp"
    ]
  },
  "SmobiOutboundSmsMessageContentV2": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "Text content of the message",
        "example": "Hello, world!"
      },
      "downloadUrl": {
        "type": "string",
        "description": "Download URL of media content",
        "example": "https://api-us.nexmo.com/v3/media/ae1467c0-1485-4fe5-b627-2a82e6eb856b"
      },
      "fileExtension": {
        "type": "string",
        "description": "File extension of the media content",
        "example": "PNG"
      }
    }
  },
  "SmobiTextMessageContentV2": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "TEXT"
        ],
        "description": "Type of message content",
        "example": "TEXT"
      },
      "content": {
        "type": "string",
        "description": "Text content",
        "example": "Hello, world!"
      }
    },
    "required": [
      "type",
      "content"
    ]
  },
  "SmobiContentMessageContentV2": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "CONTENT"
        ],
        "description": "Type of message content",
        "example": "CONTENT"
      },
      "content": {
        "description": "Content details",
        "allOf": [
          {
            "$ref": "#/components/schemas/SmobiContentDetailsV2"
          }
        ]
      }
    },
    "required": [
      "type",
      "content"
    ]
  },
  "SmobiContentDetailsV2": {
    "type": "object",
    "properties": {
      "downloadUrl": {
        "type": "string",
        "description": "Download URL of the content",
        "example": "https://api-us.nexmo.com/v3/media/ae1467c0-1485-4fe5-b627-2a82e6eb856b"
      },
      "fileExtension": {
        "type": "string",
        "description": "File extension of the content, always present when downloadUrl is present",
        "example": "PNG"
      }
    },
    "required": [
      "downloadUrl",
      "fileExtension"
    ]
  },
  "SmobiLocationMessageContentV2": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "LOCATION"
        ],
        "description": "Type of message content",
        "example": "LOCATION"
      },
      "content": {
        "description": "Location details",
        "allOf": [
          {
            "$ref": "#/components/schemas/SmobiLocationDetailsV2"
          }
        ]
      }
    },
    "required": [
      "type",
      "content"
    ]
  },
  "SmobiLocationDetailsV2": {
    "type": "object",
    "properties": {
      "latitude": {
        "type": "number",
        "description": "Latitude of the location",
        "example": 37.7749
      },
      "longitude": {
        "type": "number",
        "description": "Longitude of the location",
        "example": -122.4194
      }
    },
    "required": [
      "latitude",
      "longitude"
    ]
  },
  "SmobiSuggestionMessageContentV2": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "SUGGESTION"
        ],
        "description": "Type of message content - represents user interactions (reply/button)",
        "example": "SUGGESTION"
      },
      "content": {
        "description": "Suggestion interaction details",
        "allOf": [
          {
            "$ref": "#/components/schemas/SmobiSuggestionDetailsV2"
          }
        ]
      }
    },
    "required": [
      "type",
      "content"
    ]
  },
  "SmobiSuggestionDetailsV2": {
    "type": "object",
    "properties": {
      "parentSmobiMessageId": {
        "type": "string",
        "description": "The ID of the parent message in the Smobi system",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      },
      "parentClientRef": {
        "type": "string",
        "description": "The client reference of the parent message",
        "example": "client-ref-123"
      },
      "suggestionId": {
        "type": "string",
        "description": "The ID of the selected suggestion",
        "example": "suggestion-123"
      },
      "text": {
        "type": "string",
        "description": "The text of the selected suggestion",
        "example": "Yes, I agree"
      }
    },
    "required": [
      "parentSmobiMessageId",
      "parentClientRef",
      "suggestionId",
      "text"
    ]
  }
}
```