Create and send a poll in a chat

client.Chats.Polls.New(ctx, chatID, body) (*PollEnvelope, error)

POST/v3/chats/{chatId}/polls

Create an iMessage poll in an existing chat and send it. Polls are iMessage-only.

The chat must already exist — a poll cannot be the first message of a new chat (use POST /v3/chats for that). Options are add-only and immutable: you can add options later via POST /v3/messages/{messageId}/poll/options, but never edit or remove them.

ParametersExpand Collapse

chatID string

formatuuid

body ChatPollNewParams

Poll param.Field[ChatPollNewParamsPoll]

Poll content to create. A poll needs at least two options. Options are add-only and immutable — there is no title/question (send that as a normal text message).

Options []ChatPollNewParamsPollOption

Text string

IdempotencyKey stringOptional

Optional key to deduplicate the poll creation.

ReturnsExpand Collapse

type PollEnvelope struct{…}

Message-level envelope returned by every poll endpoint.

ChatID string

formatuuid

CreatedAt Time

formatdate-time

MessageID string

The poll-definition message’s ID — reference this poll by it.

formatuuid

Poll Poll

Poll content — options and the aggregate voter count.

Options []PollOption

CanBeEdited bool

CreatorHandle ChatHandle

The participant who added this option (poll creator for the initial options; whoever added later ones).

ID string

Unique identifier for this handle

formatuuid

Handle string

Phone number (E.164) or email address of the participant

JoinedAt Time

When this participant joined the chat

formatdate-time

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeIMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

IsMe boolOptional

Whether this handle belongs to the sender (your phone number)

LeftAt TimeOptional

When they left (if applicable)

formatdate-time

Status ChatHandleStatusOptional

Participant status

One of the following:

const ChatHandleStatusActive ChatHandleStatus = "active"

const ChatHandleStatusLeft ChatHandleStatus = "left"

const ChatHandleStatusRemoved ChatHandleStatus = "removed"

OptionID string

formatuuid

Text string

Voters []PollOptionVoter

Participants who voted for this option (vote_count = voters.length).

Handle string

VotedAt Time

formatdate-time

TotalVoters int64

Distinct participants across the whole poll (a voter picking two options counts once).

Reactions []Reaction

Tapbacks/stickers on the whole poll (message part 0).

Handle ChatHandle

ID string

Unique identifier for this handle

formatuuid

Handle string

Phone number (E.164) or email address of the participant

JoinedAt Time

When this participant joined the chat

formatdate-time

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeIMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

IsMe boolOptional

Whether this handle belongs to the sender (your phone number)

LeftAt TimeOptional

When they left (if applicable)

formatdate-time

Status ChatHandleStatusOptional

Participant status

One of the following:

const ChatHandleStatusActive ChatHandleStatus = "active"

const ChatHandleStatusLeft ChatHandleStatus = "left"

const ChatHandleStatusRemoved ChatHandleStatus = "removed"

IsMe bool

Whether this reaction is from the current user

Type ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:

const ReactionTypeLove ReactionType = "love"

const ReactionTypeLike ReactionType = "like"

const ReactionTypeDislike ReactionType = "dislike"

const ReactionTypeLaugh ReactionType = "laugh"

const ReactionTypeEmphasize ReactionType = "emphasize"

const ReactionTypeQuestion ReactionType = "question"

const ReactionTypeCustom ReactionType = "custom"

const ReactionTypeSticker ReactionType = "sticker"

CustomEmoji stringOptional

Custom emoji if type is “custom”, null otherwise

Sticker ReactionStickerOptional

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

FileName stringOptional

Filename of the sticker

Height int64Optional

Sticker image height in pixels

MimeType stringOptional

MIME type of the sticker image

URL stringOptional

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

Width int64Optional

Sticker image width in pixels

UpdatedAt Time

formatdate-time

Create and send a poll in a chat

package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  pollEnvelope, err := client.Chats.Polls.New(
    context.TODO(),
    "550e8400-e29b-41d4-a716-446655440000",
    linqgo.ChatPollNewParams{
      Poll: linqgo.ChatPollNewParamsPoll{
        Options: []linqgo.ChatPollNewParamsPollOption{linqgo.ChatPollNewParamsPollOption{
          Text: "Tacos",
        }, linqgo.ChatPollNewParamsPollOption{
          Text: "Sushi",
        }},
        IdempotencyKey: linqgo.String("poll-abc123"),
      },
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", pollEnvelope.ChatID)
}

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2019-12-27T18:11:19.117Z",
  "message_id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
  "poll": {
    "options": [
      {
        "can_be_edited": true,
        "creator_handle": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "handle": "+15551234567",
          "joined_at": "2025-05-21T15:30:00.000-05:00",
          "service": "iMessage",
          "is_me": false,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        },
        "option_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "text": "Tacos",
        "voters": [
          {
            "handle": "+14155559876",
            "voted_at": "2019-12-27T18:11:19.117Z"
          }
        ]
      }
    ],
    "total_voters": 0
  },
  "reactions": [
    {
      "handle": {
        "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
        "handle": "+15551234567",
        "joined_at": "2025-05-21T15:30:00.000-05:00",
        "service": "iMessage",
        "is_me": false,
        "left_at": "2019-12-27T18:11:19.117Z",
        "status": "active"
      },
      "is_me": false,
      "type": "love",
      "custom_emoji": null,
      "sticker": {
        "file_name": "sticker.png",
        "height": 420,
        "mime_type": "image/png",
        "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
        "width": 420
      }
    }
  ],
  "updated_at": "2019-12-27T18:11:19.117Z"
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 429,
    "code": 1007,
    "message": "Rate limited. Try again in 45 seconds.",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1007/",
    "retry_after": 45
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2019-12-27T18:11:19.117Z",
  "message_id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
  "poll": {
    "options": [
      {
        "can_be_edited": true,
        "creator_handle": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "handle": "+15551234567",
          "joined_at": "2025-05-21T15:30:00.000-05:00",
          "service": "iMessage",
          "is_me": false,
          "left_at": "2019-12-27T18:11:19.117Z",
          "status": "active"
        },
        "option_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "text": "Tacos",
        "voters": [
          {
            "handle": "+14155559876",
            "voted_at": "2019-12-27T18:11:19.117Z"
          }
        ]
      }
    ],
    "total_voters": 0
  },
  "reactions": [
    {
      "handle": {
        "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
        "handle": "+15551234567",
        "joined_at": "2025-05-21T15:30:00.000-05:00",
        "service": "iMessage",
        "is_me": false,
        "left_at": "2019-12-27T18:11:19.117Z",
        "status": "active"
      },
      "is_me": false,
      "type": "love",
      "custom_emoji": null,
      "sticker": {
        "file_name": "sticker.png",
        "height": 420,
        "mime_type": "image/png",
        "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
        "width": 420
      }
    }
  ],
  "updated_at": "2019-12-27T18:11:19.117Z"
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 429,
    "code": 1007,
    "message": "Rate limited. Try again in 45 seconds.",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1007/",
    "retry_after": 45
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}