---
url: "https://vueda.dev/v3/reference/api/py/vueda.vdq.handlers/TwilioQueueItemHandler.md"
title: "TwilioQueueItemHandler"
---

# TwilioQueueItemHandler

## Overview

Handles sending SMS messages and syncing delivery status via the Twilio API.
Instantiating this class with ``TWILIO_ACCOUNT_SID`` in settings initializes
the Twilio client; without it the handler is a no-op.

## `pull_sms_status` {#pull_sms_status}

Poll Twilio for messages sent since the queue item's date and update their status.

### Signature {#pull_sms_status-signature}

`pull_sms_status(self, qi)`

#### Parameters {#pull_sms_status-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| self |  | yes |  |  |
| <span id="pull_sms_status-param-qi">qi</span> |  | yes |  |  |

### Source {#pull_sms_status-source}

`server/vueda/vdq/handlers.py:249`

## `pull_sms_timeout_only` {#pull_sms_timeout_only}

Check awaiting SMS queue items that have exceeded the timeout window (default 2 hours).
Fetches each message's current status from Twilio and transitions timed-out items to
``timeout`` if no final status is available.

### Signature {#pull_sms_timeout_only-signature}

`pull_sms_timeout_only(self)`

#### Parameters {#pull_sms_timeout_only-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| self |  | yes |  |  |

### Source {#pull_sms_timeout_only-source}

`server/vueda/vdq/handlers.py:269`

## `send_sms` {#send_sms}

Send an SMS for the given ``QueueItem`` via Twilio. The status callback URL carries the item's
primary key, so a status update can find the item before VDQ stores the message SID. Transitions
the item to ``await`` on success, or ``error`` on ``TwilioRestException``. A status update that
reached the item first keeps the state and ``result`` it set.

### Signature {#send_sms-signature}

`send_sms(self, qi)`

#### Parameters {#send_sms-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| self |  | yes |  |  |
| <span id="send_sms-param-qi">qi</span> |  | yes |  |  |

### Source {#send_sms-source}

`server/vueda/vdq/handlers.py:195`

## `update_sms_qi` {#update_sms_qi}

Update a ``QueueItem`` based on a Twilio ``message_status`` string.
Transitions to ``succeed`` on ``delivered`` and to ``error`` on ``undelivered`` or ``failed``, from
``sending`` as well as from ``awaiting``. Any other status moves a ``sending`` item to ``awaiting``
when it is in flight (``queued``, ``sending``, ``sent``), and times out an ``awaiting`` item that has
waited longer than the configured timeout. Otherwise it changes nothing.

### Signature {#update_sms_qi-signature}

`update_sms_qi(self, queue_item, message_status, message, webhook, error_code)`

#### Parameters {#update_sms_qi-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| self |  | yes |  |  |
| <span id="update_sms_qi-param-queue_item">queue_item</span> |  | yes |  |  |
| <span id="update_sms_qi-param-message_status">message_status</span> |  | yes |  |  |
| <span id="update_sms_qi-param-message">message</span> |  | no | `None` |  |
| <span id="update_sms_qi-param-webhook">webhook</span> |  | no | `False` |  |
| <span id="update_sms_qi-param-error_code">error_code</span> |  | no | `''` |  |

### Source {#update_sms_qi-source}

`server/vueda/vdq/handlers.py:303`

## `twilio_client` {#twilio_client}

## Source

`server/vueda/vdq/handlers.py:177`