# Events

## Overview

Twilio Communications API provides event types for tracking message delivery, failures, reads, and operational status. You can subscribe to these events to receive real-time notifications and automate workflows based on message outcomes.

## Operation events

### Operation processing

This event notifies you when Twilio is processing messages in a specific operation.

Subscribe to this event to monitor the progress of a bulk message send.

* **Subscription event type**: `com.twilio.comms-api.operation.processing`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.OperationProcessing/2`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.OperationProcessing/2",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Operations Processing Event Schema",
  "description": "Indicates that messages in an operation are being processed.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    }
  },
  "additionalProperties": false
}
```

### Operation completed

This event notifies you when Twilio has finished processing all messages in a specific operation.

* **Subscription event**: `com.twilio.comms-api.operation.completed`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.OperationCompleted/2`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.OperationCompleted/2",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Operation Completed Event Schema",
  "description": "Indicates that messages in an operation are done processing.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    }
  },
  "additionalProperties": false
}
```

### Operation scheduled

This event notifies you when Twilio has scheduled messages in a specific operation for future delivery.

* **Subscription event**: `com.twilio.comms-api.operation.scheduled`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.OperationScheduled/2`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.OperationScheduled/2",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Operations scheduled Event Schema",
  "description": "Indicates that messages in an operation are being scheduled.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    }
  },
  "additionalProperties": false
}
```

## Message events

### Message queued

This event notifies you when Twilio has accepted a message and placed it in the queue for processing.

* **Subscription event**: `com.twilio.comms-api.message.queued`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageQueued/3`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageQueued/3",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Queued Event Schema",
  "description": "Indicates that the message has been accepted by the system and is waiting to be processed.",
  "required": [],
  "properties": {
    "account_sid": {
      "type": "string",
      "description": "Twilio Account SID"
    },
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was queued"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message sent

This event notifies you when Twilio has successfully transmitted a message to the carrier.

* **Subscription event**: `com.twilio.comms-api.message.sent`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageSent/4`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageSent/4",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Sent Event Schema",
  "description": "Indicates a successful transmission of a message to the carrier.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was sent"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message failed

This event notifies you when a message has failed to be sent or processed.

* **Subscription event**: `com.twilio.comms-api.message.failed`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageFailed/4`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageFailed/4",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Failed Event Schema",
  "description": "Indicates that a message has failed to be sent or processed.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message failed"
    },
    "error_code": {
      "type": "string",
      "description": "Error code associated with the failure"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message delivered

This event notifies you when a message has been successfully delivered to the recipient.

* **Subscription event**: `com.twilio.comms-api.message.delivered`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageDelivered/4`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageDelivered/4",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Delivered Event Schema",
  "description": "Indicates that a message has been successfully delivered to the recipient.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was delivered"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message undelivered

This event notifies you when Twilio receives a delivery receipt indicating that the message was not delivered.

* **Subscription event**: `com.twilio.comms-api.message.undelivered`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageUndelivered/4`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageUndelivered/4",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Undelivered Event Schema",
  "description": "Indicates that Twilio has received a delivery receipt indicating that the message was not delivered",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was undelivered"
    },
    "error_code": {
      "type": "string",
      "description": "Error code associated with the failure"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message read

This event notifies you when a message, such as a WhatsApp message, has been read by the recipient.

* **Subscription event**: `com.twilio.comms-api.message.read`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageRead/4`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageRead/4",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Read Event Schema",
  "description": "Schema for message read events. For example, when a whatsapp message is read by the recipient.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "attempt": {
      "type": "string",
      "description": "Attempt number for the operation"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was sent"
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Array of tag objects containing key-value pairs"
    }
  },
  "additionalProperties": false
}
```

### Message inbound

This event notifies you when an inbound message has been received, for example, when a user sends a reply via RCS or WhatsApp.

* **Subscription event**: `com.twilio.comms-api.message.inbound-received`
* **Event schema**: `https://events-schemas.twilio.com/CommsApi.MessageInbound/2`

**Example event payload:**

```json
{
  "$id": "https://events-schemas.twilio.com/CommsApi.MessageInbound/2",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Message Inbound Event Schema",
  "description": "Schema for message inbound events. For example, when a rcs message is received from a user.",
  "required": [],
  "properties": {
    "operation_id": {
      "type": "string",
      "description": "Unique identifier for the operation"
    },
    "message_id": {
      "type": "string",
      "description": "Unique identifier for the message record"
    },
    "downstream_id": {
      "type": "string",
      "description": "Identifier for the downstream system where the message was sent"
    },
    "session_id": {
      "type": "string",
      "description": "Identifier for the session associated with the message"
    },
    "to": {
      "type": "object",
      "description": "Object containing the destination of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the destination"
        },
        "address": {
          "type": "string",
          "description": "Address of the destination"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "from": {
      "type": "object",
      "description": "Object containing the source of the message",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the source"
        },
        "address": {
          "type": "string",
          "description": "Address of the source"
        },
        "channel": {
          "type": "string",
          "description": "Channel used to send the message. This can be 'sms', 'whatsapp', 'rcs'"
        }
      }
    },
    "content": {
      "type": "object",
      "description": "Object containing the content of the message",
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string",
          "description": "Text content of the message"
        }
      }
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Object containing key-value pairs for tags"
    },
    "channel_metadata": {
      "type": "object",
      "description": "Object containing channel specific metadata",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}
```

## Subscribe to the Twilio Communications API events

Use the following cURL command to [create a subscription](/docs/events/event-streams/subscription#create-a-subscription) to the Twilio Communications API events:

```bash
curl -X POST "https://events.twilio.com/v1/Subscriptions" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.operation.completed\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.operation.processing\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.operation.scheduled\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.read\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.sent\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.delivered\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.failed\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.undelivered\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.queued\"}" \
--data-urlencode "Types={\"type\":\"com.twilio.comms-api.message.inbound-received\"}" \
--data-urlencode "Description=\"Twilio Communications API subscriptions events\"" \
--data-urlencode "SinkSid={{Twilio_EventStreams_Sink_SID}}" \
-u {{Twilio_Account_SID}}:{{Twilio_Auth_Token}} | jq
```