PUT Polls

Update Poll

When creating a poll, provide the desired values.

PUT /api/v3/{appid}/poll/poll/{pollid}/update

This method requires authentication.

When creating a poll, provide the desired values. When updating an existing poll, only provide the values to overwrite. To delete a value, pass an empty string.

METADATA

* ownerid: (required) The userid of the owner of the poll

DISPLAY PROPERTIES

* title: (required) The title of the poll. Required on create. Optional on update.
* description: (optional) The description of the poll
* pictureurl: (optional) The URL for a picture for the room
* embedcontenttop: (optional) Content to be displayed at the top of the poll
* embedcontentbottom: (optional) Content to be displayed at the bottom of the poll
* displayresults: (optional) [default="aftervote"/always/pollclosed] Use "aftervote" to display results after a vote is over. Set to "always" to return current standings. Set to "pollclosed" to only allow poll results to be disclosed when the poll is closed.
* sortchoices: (optional, "random" or "asconfigured", default = "asconfigured") When retrieving the list of response choices they can be displayed in the order you specified or in random order.

BEHAVIOR SETTINGS

* allowmultiplechoicesperuser: ("true" or default = "false") If true, the user may submit answers for more than one choice.
* maxtotalresponsesperuser: (default = 1). This is the number of times that a user can respond to the poll, the total of all responses regardless of which choice was selected.
* maxresponsesperchoiceperuser: (default = 1). The maximum time a user may submit a response per choice. For example you can make it so the user can respond 3 times but must select a different choice with each response, o ryou could allow the user to vote as many times as desired per choice with all their available responses.

AUTO PUBLISH SETTINGS

* whenpollpublish: (optional) [default=now] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time.
* whenpollexpires: (optional) [default=null] An ISO-8601 date time. If specified, the poll transitions to the expired state at this time and is no longer returned by the API (It only exists as archived data).
* whenpollopens: (optional) [default=now] An ISO-8601 date time. Now by default. If specified, poll is not open until this time and no one can respond until then.
* whenpollcloses: (optional) [default=null] An ISO-8601 date time. Null by default. If specified, poll transitions to closed state at this time and doesn't accept responses.

CUSTOM FIELDS

* customid: (optional) A customid for the room. Can be unused, or a unique key. If provided, and a poll with that customid is already created this call will update the existing poll.
* customtype : (optional) Custom type string.
* custompayload : (optional) Custom payload string.
* customfield1 : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.
* customfield2 : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.
* customtags : (optional) A comma delimited list of tags

Request

Parameters

Values in the path and query string.

appid path

string TalkLabs ID required

The TalkLabs application ID assigned to your account.

Example: your-app-id

pollid path

string TalkLabs ID required

The TalkLabs assigned poll ID.

Example: poll-id

Request

JSON body

Send as application/json.

ownerUserId

string customer-defined

title

string

subtitle

string

description

string

pictureUrl

string

embedContentTop

string

embedContentBottom

string

videoId

string

displayResults

integer · int32

sortChoices

integer · int32

maxTotalResponsesPerUser

integer · int32

The maximum number of votes an individual can cast

allowMultipleChoicesPerUser

boolean

Should users be allowed to vote for more than one response choice

maxResponsesPerChoicePerUser

integer · int32

The maximum number of times a user can vote for a single choice

whenPollPublish

string · date-time

whenPollOpens

string · date-time

whenPollCloses

string · date-time

whenPollExpires

string · date-time

allowAnonymousPolling

boolean

leadCaptureEnabled

boolean

leadCaptureRequired

boolean

leadCaptureName

boolean

leadCaptureTitle

string

leadCaptureDescription

string

leadCapturePrompt

string

socialShareEnable

boolean

socialHandleFacebook

string

socialHandleX

string

socialHandleTikTok

string

socialHandleWhatsApp

string

socialCardTitle

string

socialCardImageUrl

string

socialCardUrl

string

customType

string

customId

string customer-defined

A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.

customPayload

string

customField1

string

customField2

string

customTags

string[]

Request example

{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}

Response

Status codes

Every JSON response uses the API result envelope.

200 OK ApiResult

400 Bad Request ApiResult

403 Forbidden ApiResult

500 Internal Server Error ApiResult

Example response · 200

{
  "message": "Success",
  "errors": {},
  "data": {
    "kind": "poll.poll",
    "id": "662da20fe45ad80a7f2bd950",
    "appid": "662bb49bf10e9a26a7e8ed92",
    "ownerid": "u-8842",
    "title": "Sample Poll 1: Vote for your favorite color",
    "description": "Vote for your favorite color",
    "posterurl": "",
    "embedcontenttop": "",
    "embedcontentbotton": "",
    "whenpollpublish": "2024-04-28T01:10:39.5358368Z",
    "whenpollopens": "2024-04-27T21:10:39.5358872-04:00",
    "whenpollcloses": null,
    "whenpollexpires": null,
    "displayresults": 1,
    "sortanswers": 0,
    "customtype": "",
    "customid": "sample-poll-1-vote",
    "custompayload": "",
    "customtags": [],
    "customfield1": "",
    "customfield2": ""
  }
}

curl --request PUT \
  --url "https://api.sportstalk247.com/api/v3/${APP_ID}/poll/poll/${POLL_ID}/update" \
  --header "Accept: application/json" \
  --header "x-api-token: ${TALKLABS_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}'

const appId = process.env.TALKLABS_APP_ID;
const pollid = 'poll-id';

const response = await fetch(
  `https://api.sportstalk247.com/api/v3/${appId}/poll/poll/${pollid}/update`,
{
  method: 'PUT',
  headers: {
    Accept: 'application/json',
    'x-api-token': process.env.TALKLABS_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}),
});

const result = await response.json();

import json
import os
import requests

app_id = os.environ["TALKLABS_APP_ID"]
pollid = "poll-id"

response = requests.put(
    f"https://api.sportstalk247.com/api/v3/{app_id}/poll/poll/{pollid}/update",
    headers={
        "Accept": "application/json",
        "x-api-token": os.environ["TALKLABS_API_TOKEN"],
    },
    json=json.loads(r'''{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}'''),
)
response.raise_for_status()
result = response.json()

Environment variables TALKLABS_APP_ID TALKLABS_API_TOKEN

Response