> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a poll

> POST /api/v1/comms/polls — send a native iMessage poll.

Send a native iMessage poll. On iOS 26 and later it lands as tappable choices. Older iPhones show the fallback "Sent a poll".

Polls are iMessage-only. SMS is rejected.

**Scope:** `comms_send`

## Request

```bash theme={null}
curl -X POST "https://osis.co/api/v1/comms/polls" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: poll-lunch-4242" \
  -d '{
    "to": "+12125550147",
    "question": "Where should we eat?",
    "options": ["Pizza", "Sushi", "Tacos"]
  }'
```

### Body parameters

<ParamField body="to" type="string">
  E.164 destination. Required unless `conversation_id` or `contact_id` is set.
</ParamField>

<ParamField body="conversation_id" type="string">
  Existing conversation to continue. Required unless `to` or `contact_id` is set.
</ParamField>

<ParamField body="contact_id" type="string">
  Existing contact. Required unless `to` or `conversation_id` is set.
</ParamField>

<ParamField body="question" type="string" required>
  Poll question. Max 200 characters.
</ParamField>

<ParamField body="options" type="string[]" required>
  Two to twelve distinct choices. Each option is at most 80 characters.
</ParamField>

<ParamField body="default_country" type="string">
  ISO country code used only when `to` is a national-format number.
</ParamField>

## Response

Same envelope as [Send a message](/messages-api/send-message), plus `poll`.

```json theme={null}
{
  "message": {
    "id": "msg_01HZX…",
    "conversation_id": "conv_01HZX…",
    "contact_id": "ctc_01HZX…",
    "direction": "outbound",
    "channel": "imessage",
    "body": "Where should we eat?",
    "status": "sent"
  },
  "poll": {
    "question": "Where should we eat?",
    "options": ["Pizza", "Sushi", "Tacos"]
  }
}
```

Hosted Comms agents can also send this with the `send_poll` tool.

When a contact votes, Comms records an inbound message such as `Voted "Pizza" on "Lunch?"` and emits `comms.poll.voted`. A native tap vote includes the chosen option when the line receives the vote payload; a text reply that matches an option or its number is treated the same way.