# Status Update Payload

Status V1 events report message processing and delivery outcomes. Use `smobiMessageId` and `clientRef` to associate an update with the original request.

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

## Example Payloads

### Message Delivered

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "clientRef": "client-ref-123",
  "to": "15552223333",
  "from": "15551234567",
  "status": "DELIVERED",
  "channel": "SMS",
  "timestamp": "2021-01-01T00:00:00.000Z"
}
```

### Message Failed

```json
{
  "smobiMessageId": "123e4567-e89b-12d3-a456-426614174000",
  "clientRef": "client-ref-123",
  "to": "15552223333",
  "from": "15551234567",
  "status": "FAILED",
  "channel": "SMS",
  "timestamp": "2021-01-01T00:00:00.000Z",
  "failureDetails": {
    "reason": "UNDELIVERABLE",
    "description": "The message could not be delivered"
  }
}
```

## 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/OutboundStatusV1"
}
```

## Referenced Schemas

```json
{
  "OutboundStatusV1": {
    "type": "object",
    "properties": {
      "smobiMessageId": {
        "type": "string",
        "description": "The reference number of the message in the Smobi system",
        "example": "123e4567-e89b-12d3-a456-426614174000"
      },
      "clientRef": {
        "type": "string",
        "description": "The reference number of the message in the client system",
        "example": "client-ref-123"
      },
      "to": {
        "type": "string",
        "description": "The phone number of the recipient",
        "example": "15552223333"
      },
      "from": {
        "type": "string",
        "description": "The phone number of the sender",
        "example": "15551234567"
      },
      "status": {
        "type": "string",
        "description": "The status of the message",
        "enum": [
          "PROCESSING",
          "SENT",
          "FAILED",
          "DELIVERED",
          "READ"
        ],
        "example": "DELIVERED"
      },
      "channel": {
        "type": "string",
        "description": "The channel of the message",
        "enum": [
          "SMS",
          "RCS"
        ],
        "example": "SMS"
      },
      "timestamp": {
        "type": "string",
        "description": "The timestamp of the status update",
        "example": "2021-01-01T00:00:00.000Z"
      },
      "failureDetails": {
        "description": "Additional details about the status (for failed messages)",
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookStatusReasonV1"
          }
        ]
      }
    },
    "required": [
      "smobiMessageId",
      "clientRef",
      "to",
      "from",
      "status",
      "channel",
      "timestamp"
    ]
  },
  "WebhookStatusReasonV1": {
    "type": "object",
    "properties": {
      "reason": {
        "type": "string",
        "description": "The reason for the status",
        "enum": [
          "REJECTED",
          "OPTED_OUT",
          "UNDELIVERABLE"
        ],
        "example": "REJECTED"
      },
      "description": {
        "type": "string",
        "description": "The description of the status reason",
        "example": "Resource size is too large"
      }
    },
    "required": [
      "reason"
    ]
  }
}
```