API reference

Audiences API

Named contact lists to send against. Import E.164 contacts once, then reference the audience instead of passing recipient arrays around.

GET/audiencesaudiences:read

List audiences

List and filter the org's contact lists.

Arguments

Name	Type	In	Description
`q`	string	query	Free-text search over the name.
`page`	number	query	—
`pageSize`	number	query	—

Request

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

Same call, as a tool

# MCP tool name
search_audiences

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

GET/audiences/:idaudiences:read

Fetch one audience

Fetch one audience and its size.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

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

Same call, as a tool

# MCP tool name
get_audience

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

GET/audiences/:id/contactsaudiences:read

Page through contacts

Page through the contacts inside an audience.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`page`	number	query	—
`pageSize`	number	query	—

Request

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

Same call, as a tool

# MCP tool name
list_audience_contacts

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

POST/audiencesaudiences:write

Create an audience

Create a new contact list for an agent to send against.

Arguments

Name	Type	In	Description
`name`required	string	body	—
`description`	string	body	—
`source`	string	body	Free-text provenance, e.g. "Jaipur wedding planners leads.csv".
`contacts`	object[]	body	—

Request

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

Same call, as a tool

# MCP tool name
create_audience

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

POST/audiences/:id/contactsaudiences:write

Import contacts

Bulk-add E.164 contacts to an audience — the step that turns a spreadsheet into a sendable list.

Arguments

Name	Type	In	Description
`id`required	string	path	—
`contacts`required	object[]	body	—

Request

curl -X POST "https://your-server/api/agent/audiences/<id>/contacts" \
  -H "Authorization: Bearer $WA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": <object[]>
  }'

Same call, as a tool

# MCP tool name
import_contacts

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

DELETE/audiences/:idaudiences:write

Delete an audience

Remove an audience from the org.

Arguments

Name	Type	In	Description
`id`required	string	path	—

Request

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

Same call, as a tool

# MCP tool name
delete_audience

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