API reference

Surveys API

Conversational surveys are multi-turn templates: a question set with branching, sent to an audience, with answers that come back as structured data. They go through the same approval gate as templates.

GET/surveyssurveys:read

Search surveys

Find conversational surveys by query across the library and your org.

Arguments

Name	Type	In	Description
`q`	string	query	Free-text search over the name.
`status`	string	query	—DRAFT \| SCHEDULED \| ACTIVE \| CLOSED
`page`	number	query	—
`pageSize`	number	query	—

Request

curl -X GET "https://your-server/api/agent/surveys" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
search_surveys

# CLI (planned)
$ wa surveys [query] [--status ACTIVE]

GET/surveys/:idsurveys:read

Fetch one survey

Fetch one survey — its questions, branching, and current approval state.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X GET "https://your-server/api/agent/surveys/<id>" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
get_survey

# CLI (planned)
$ wa survey get <id>

POST/surveys/:id/rendersurveys:read

Preview the conversation

Preview the whole conversation as the recipient will walk it, before anything is sent.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X POST "https://your-server/api/agent/surveys/<id>/render" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
render_survey

# No CLI command for this call yet —
# use the HTTP route or the MCP tool.

POST/surveyssurveys:write

Create a survey

Author a new conversational survey from a question set.

Arguments

Name	Type	In	Description
`name`required	string	body	—
`description`	string	body	—
`definition`required	object	body	SurveyDefinition: { intro?, outro?, questions: [{ questionId, prompt, type, options?, minRating?, maxRating?, required? }] }.
`startDate`	string	body	ISO date; schedules the survey.
`endDate`	string	body	—
`timezone`	string	body	—
`languageCode`	string[]	body	—
`isPreferencesSurvey`	boolean	body	—
`channel`	string	body	Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand.RCS \| WHATSAPP

Request

curl -X POST "https://your-server/api/agent/surveys" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": <string>,
    "definition": <object>
  }'

Same call, as a tool

# MCP tool name
create_survey

# CLI (planned)
$ wa survey create --file <survey.json>

POST/surveys/:id/clonemarketplace:clone

Clone into your org

Copy a published survey into your org as a private draft.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X POST "https://your-server/api/agent/surveys/<id>/clone" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
clone_survey

# No CLI command for this call yet —
# use the HTTP route or the MCP tool.

DELETE/surveys/:idsurveys:write

Delete a survey

Remove a survey you own from the org.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X DELETE "https://your-server/api/agent/surveys/<id>" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
delete_survey

# No CLI command for this call yet —
# use the HTTP route or the MCP tool.

POST/surveys/:id/submitsurveys:submit

Submit for approval

Send a survey for provider approval — the same gate templates pass through.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`channel`	string	body	Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand.RCS \| WHATSAPP

Request

curl -X POST "https://your-server/api/agent/surveys/<id>/submit" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": <string>
  }'

Same call, as a tool

# MCP tool name
submit_survey

# CLI (planned)
$ wa survey submit <id>

POST/surveys/:id/sendsurveys:send

Run against an audience

Run the survey against an audience. Billable and irreversible — rehearse with send_survey_test first.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`to`	string[]	body	E.164 destinations, e.g. ["+15551234567"].
`audienceIds`	string[]	body	—
`channel`	string	body	Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand.RCS \| WHATSAPP

Request

curl -X POST "https://your-server/api/agent/surveys/<id>/send" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": <string[]>,
    "audienceIds": <string[]>,
    "channel": <string>
  }'

Same call, as a tool

# MCP tool name
send_survey

# CLI (planned)
$ wa survey send <id> [--to +1555...] [--audience <id>]

PATCH/surveys/:idsurveys:write

Patch a survey

Patch a survey's questions, branching, or metadata.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`name`	string	body	—
`description`	string	body	—
`definition`	object	body	—
`status`	string	body	—DRAFT \| SCHEDULED \| ACTIVE \| CLOSED
`startDate`	string	body	—
`endDate`	string	body	—
`audienceIds`	string[]	body	—
`channel`	string	body	Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand.RCS \| WHATSAPP

Request

curl -X PATCH "https://your-server/api/agent/surveys/<id>" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": <string>,
    "description": <string>,
    "definition": <object>,
    "status": <string>,
    "startDate": <string>,
    "endDate": <string>,
    "audienceIds": <string[]>,
    "channel": <string>
  }'

Same call, as a tool

# MCP tool name
update_survey

# CLI (planned)
$ wa survey update <id> --file <patch.json>

GET/surveys/:id/sendssurveys:read

Send history

Read the send history for one survey — who it went to and when.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X GET "https://your-server/api/agent/surveys/<id>/sends" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
list_survey_sends

# CLI (planned)
$ wa survey sends <id>

POST/surveys/:id/send-testsurveys:send

Send yourself a test

Send the survey to yourself first. The rehearsal that keeps a broken branch from reaching an audience.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`number`required	string	body	E.164, e.g. +15551234567.
`channel`	string	body	Channel to act on (RCS or WHATSAPP). Defaults to your org's own brand channel; any other channel requires the matching add-on brand.RCS \| WHATSAPP

Request

curl -X POST "https://your-server/api/agent/surveys/<id>/send-test" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": <string>
  }'

Same call, as a tool

# MCP tool name
send_survey_test

# CLI (planned)
$ wa survey send-test <id> --to +1555...

GET/surveys/:id/resultsresults:read

Read responses

Pull the answers back as structured data, so the agent that ran the survey can act on what it learned.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

curl -X GET "https://your-server/api/agent/surveys/<id>/results" \
  -H "Authorization: Bearer $WA_AGENT_KEY"

Same call, as a tool

# MCP tool name
get_results

# CLI (planned)
$ wa survey results <id>

POST/media/uploadsurveys:write

Host card media

Host an image or video for use as rich-card media.

Arguments

Name	Type	In	Description
`base64`	string	body	Raw base64 or data: URL of the image bytes.
`mime`	string	body	Image MIME type (required with base64), e.g. image/png.
`filename`	string	body	—
`sourceUrl`	string	body	https image URL to fetch and re-host onto GCS.

Request

curl -X POST "https://your-server/api/agent/media/upload" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": <string>,
    "mime": <string>,
    "filename": <string>,
    "sourceUrl": <string>
  }'

Same call, as a tool

# MCP tool name
upload_media

# CLI (planned)
$ wa upload-image (--file <image.png> | --from-url <url>)