WATI API reference

New to Corsair? See API access, authentication, and error handling.

Account

credits

account.credits Read the workspace messaging credit balance Risk: read

await corsair.wati.api.account.credits({});

Input: empty object Output

Name	Type	Required	Description
`credit`	`number \| null`	No	The credit balance.
`welcome_credit`	`number \| null`	No	—
`remaining_free_conversations_count`	`number \| null`	No	—
`currency`	`string \| null`	No	—
`auto_charge_enabled`	`boolean \| null`	No	—

Broadcasts

get

broadcasts.get Read one campaign Risk: read

await corsair.wati.api.broadcasts.get({ broadcast_id: 'bc-1' });

Input

Name	Type	Required	Description
`broadcast_id`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`broadcast_id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`status`	`string \| null`	No	—
`template_name`	`string \| null`	No	—
`template_id`	`string \| null`	No	—
`channel_id`	`string \| null`	No	—
`created`	`string \| null`	No	—
`last_updated`	`string \| null`	No	—
`scheduled`	`string \| null`	No	—
`scheduled_at`	`string \| null`	No	—
`statistics`	`Record<string, number \| null> \| null`	No	—
`sent`	`number \| null`	No	—
`delivered`	`number \| null`	No	—
`read`	`number \| null`	No	—
`failed`	`number \| null`	No	—

list

broadcasts.list List campaigns with their delivery counts Risk: read

await corsair.wati.api.broadcasts.list({ page_number: 1, date_from: '2026-11-01', date_to: '2026-11-30' });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.
`date_from`	`string`	Yes	Campaigns created from this date, e.g. 2026-11-01.
`date_to`	`string`	Yes	Campaigns created up to this date, e.g. 2026-11-30.
`channel`	`string`	No	Only campaigns sent from this channel.

Output

Name	Type	Required	Description
`broadcasts`	`object[] \| null`	No	—
`broadcast_list`	`object[] \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

broadcasts full type

{
  id?: string | null,
  broadcast_id?: string | null,
  name?: string | null,
  status?: string | null,
  template_name?: string | null,
  template_id?: string | null,
  channel_id?: string | null,
  created?: string | null,
  last_updated?: string | null,
  scheduled?: string | null,
  scheduled_at?: string | null,
  statistics?: Record<string, number | null> | null,
  sent?: number | null,
  delivered?: number | null,
  read?: number | null,
  failed?: number | null
}[] | null

broadcast_list full type

{
  id?: string | null,
  broadcast_id?: string | null,
  name?: string | null,
  status?: string | null,
  template_name?: string | null,
  template_id?: string | null,
  channel_id?: string | null,
  created?: string | null,
  last_updated?: string | null,
  scheduled?: string | null,
  scheduled_at?: string | null,
  statistics?: Record<string, number | null> | null,
  sent?: number | null,
  delivered?: number | null,
  read?: number | null,
  failed?: number | null
}[] | null

recipients

broadcasts.recipients Read per-recipient delivery outcomes for a campaign Risk: read

await corsair.wati.api.broadcasts.recipients({ broadcast_id: 'bc-1', page_number: 1 });

Input

Name	Type	Required	Description
`broadcast_id`	`string`	Yes	—
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

Output

Name	Type	Required	Description
`recipients`	`object[] \| null`	No	—
`recipient_list`	`object[] \| null`	No	—
`total_count`	`number \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

recipients full type

{
  id?: string | null,
  contact_id?: string | null,
  contact_name?: string | null,
  contact_phone?: string | null,
  failed_code?: string | null,
  message_id?: string | null,
  local_message_id?: string | null,
  created?: string | null,
  wa_id?: string | null,
  phone?: string | null,
  name?: string | null,
  status?: string | null,
  sent?: string | null,
  delivered?: string | null,
  read?: string | null,
  error?: string | null
}[] | null

recipient_list full type

{
  id?: string | null,
  contact_id?: string | null,
  contact_name?: string | null,
  contact_phone?: string | null,
  failed_code?: string | null,
  message_id?: string | null,
  local_message_id?: string | null,
  created?: string | null,
  wa_id?: string | null,
  phone?: string | null,
  name?: string | null,
  status?: string | null,
  sent?: string | null,
  delivered?: string | null,
  read?: string | null,
  error?: string | null
}[] | null

Channels

list

channels.list List the channels connected to the workspace Risk: read

await corsair.wati.api.channels.list({ page_number: 1, page_size: 20 });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

Output

Name	Type	Required	Description
`channels`	`object[] \| null`	No	—

channels full type

{
  id?: string | null,
  channel_id?: string | null,
  name?: string | null,
  type?: string | null,
  channel?: string | null,
  status?: string | null,
  phone_number?: string | null
}[] | null

Contacts

count

contacts.count Count the contacts on the workspace Risk: read

await corsair.wati.api.contacts.count({});

Input: empty object Output

Name	Type	Required	Description
`contact_count`	`number \| null`	No	The number of contacts.

create

contacts.create Add a contact by WhatsApp number, with a name and custom attributes as name/value pairs Risk: write

await corsair.wati.api.contacts.create({ whatsapp_number: '1234567890', name: 'John Doe', custom_params: [{ name: 'age', value: '30' }] });

Input

Name	Type	Required	Description
`whatsapp_number`	`string`	Yes	The number in international form, without a leading +.
`name`	`string`	Yes	—
`custom_params`	`object[]`	No	Custom attributes, as name/value pairs.

custom_params full type

{
  name: string,
  value: string
}[]

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`wa_id`	`string \| null`	No	The WhatsApp identifier.
`name`	`string \| null`	No	—
`phone`	`string \| null`	No	—
`photo`	`string \| null`	No	—
`created`	`string \| null`	No	—
`last_updated`	`string \| null`	No	—
`contact_status`	`string \| null`	No	—
`source`	`string \| null`	No	Where the contact came from, e.g. manual.
`channel_id`	`string \| null`	No	—
`opted_in`	`boolean \| null`	No	—
`allow_broadcast`	`boolean \| null`	No	—
`allow_sms`	`boolean \| null`	No	—
`teams`	`string[] \| null`	No	—
`custom_params`	`object[] \| null`	No	—

custom_params full type

{
  name: string,
  value: string
}[] | null

delete

contacts.delete Remove a contact from the workspace (WATI documents this as a soft delete, not a physical erasure) Risk: destructive

await corsair.wati.api.contacts.delete({ target: '+1234567890' });

Input

Name	Type	Required	Description
`target`	`string`	Yes	—

Output

Name	Type	Required	Description
`success`	`boolean \| null`	No	—
`id`	`string \| null`	No	—
`contact_id`	`string \| null`	No	—
`deleted`	`boolean \| null`	No	—
`cleanup_completed`	`boolean \| null`	No	—

get

contacts.get Read one contact by wa_id or phone number, including custom attributes and opt-in state Risk: read

await corsair.wati.api.contacts.get({ target: '+1234567890' });

Input

Name	Type	Required	Description
`target`	`string`	Yes	The contact wa_id or phone number. A leading + is allowed.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`wa_id`	`string \| null`	No	The WhatsApp identifier.
`name`	`string \| null`	No	—
`phone`	`string \| null`	No	—
`photo`	`string \| null`	No	—
`created`	`string \| null`	No	—
`last_updated`	`string \| null`	No	—
`contact_status`	`string \| null`	No	—
`source`	`string \| null`	No	Where the contact came from, e.g. manual.
`channel_id`	`string \| null`	No	—
`opted_in`	`boolean \| null`	No	—
`allow_broadcast`	`boolean \| null`	No	—
`allow_sms`	`boolean \| null`	No	—
`teams`	`string[] \| null`	No	—
`custom_params`	`object[] \| null`	No	—

custom_params full type

{
  name: string,
  value: string
}[] | null

list

contacts.list Page through contacts, 100 per page at most Risk: read

await corsair.wati.api.contacts.list({ page_number: 1, page_size: 20 });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

Output

Name	Type	Required	Description
`contact_list`	`object[] \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

contact_list full type

{
  id?: string | null,
  wa_id?: string | null,
  name?: string | null,
  phone?: string | null,
  photo?: string | null,
  created?: string | null,
  last_updated?: string | null,
  contact_status?: string | null,
  source?: string | null,
  channel_id?: string | null,
  opted_in?: boolean | null,
  allow_broadcast?: boolean | null,
  allow_sms?: boolean | null,
  teams?: string[] | null,
  custom_params?: {
    name: string,
    value: string
  }[] | null
}[] | null

Conversations

list

conversations.list List conversations newest first, filtered by channel type or channel Risk: read

await corsair.wati.api.conversations.list({ page_number: 1, channel_type: 'whatsapp' });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.
`channel_type`	`string`	No	Filter by channel type, case-insensitive, such as whatsapp.
`channel_id`	`string`	No	Filter by connected channel ID.

Output

Name	Type	Required	Description
`conversation_list`	`object[] \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

conversation_list full type

{
  id?: string | null,
  conversation_id?: string | null,
  contact_id?: string | null,
  wa_id?: string | null,
  contact_name?: string | null,
  started_date?: string | null,
  last_updated?: string | null,
  phone?: string | null,
  channel_id?: string | null,
  channel_type?: string | null,
  last_message?: string | null,
  last_message_timestamp?: string | null,
  unread_count?: number | null,
  status?: string | null,
  assigned_operator?: string | null,
  assigned_team?: string | null,
  tags?: string[] | null
}[] | null

messages

conversations.messages Read the messages in one conversation; the target is a wa_id, phone number or conversation ID, not a bare contact ID Risk: read

await corsair.wati.api.conversations.messages({ target: 'conv-1', page_number: 1 });

Input

Name	Type	Required	Description
`target`	`string`	Yes	The conversation target: a contact wa_id, a phone number, or a conversation ID. Do not pass a bare contact ID, which is a different value.
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

Output

Name	Type	Required	Description
`message_list`	`object[] \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

message_list full type

{
  id?: string | null,
  message_id?: string | null,
  conversation_id?: string | null,
  wa_id?: string | null,
  message_type?: string | null,
  type?: string | null,
  event_type?: string | null,
  ticket_id?: string | null,
  owner?: boolean | null,
  operator_name?: string | null,
  local_message_id?: string | null,
  failed_detail?: string | null,
  text?: string | null,
  content?: any | null,
  status?: string | null,
  timestamp?: string | null,
  created?: string | null,
  from_me?: boolean | null,
  operator?: string | null,
  template_name?: string | null,
  media_url?: string | null
}[] | null

Messages

sendFile

messages.sendFile Send a file from a public URL, with an optional caption Risk: write

await corsair.wati.api.messages.sendFile({ target: 'conv-1', url: 'https://acme.example/invoice.pdf', caption: 'Your invoice' });

Input

Name	Type	Required	Description
`target`	`string`	Yes	—
`url`	`string`	Yes	A publicly reachable media URL.
`caption`	`string`	No	—

Output

Name	Type	Required	Description
`message`	`object \| null`	No	—

message full type

{
  id?: string | null,
  message_id?: string | null,
  conversation_id?: string | null,
  wa_id?: string | null,
  message_type?: string | null,
  type?: string | null,
  event_type?: string | null,
  ticket_id?: string | null,
  owner?: boolean | null,
  operator_name?: string | null,
  local_message_id?: string | null,
  failed_detail?: string | null,
  text?: string | null,
  content?: any | null,
  status?: string | null,
  timestamp?: string | null,
  created?: string | null,
  from_me?: boolean | null,
  operator?: string | null,
  template_name?: string | null,
  media_url?: string | null
} | null

sendTemplate

messages.sendTemplate Send an approved template with bound placeholders, optionally as a named campaign; the only route outside the service window Risk: write

await corsair.wati.api.messages.sendTemplate({ whatsapp_number: '1234567890', template_name: 'order_update', broadcast_name: 'order_update_jordan', parameters: [{ name: '1', value: 'Jordan' }] });

Input

Name	Type	Required	Description
`whatsapp_number`	`string`	Yes	The recipient number, without a leading +.
`template_name`	`string`	Yes	—
`broadcast_name`	`string`	Yes	Groups the send as a campaign under this name. Required by WATI even for a single recipient.
`parameters`	`object[]`	No	The values bound to the template placeholders, in order.
`local_message_id`	`string`	No	Your own id, which WATI echoes back for correlation.

parameters full type

{
  name: string,
  value: string
}[]

Output

Name	Type	Required	Description
`success`	`boolean \| null`	No	—
`broadcast_id`	`string \| null`	No	—
`error`	`string \| null`	No	—
`recipients`	`object[] \| null`	No	—

recipients full type

{
  local_message_id?: string | null,
  phone_number?: string | null,
  target?: string | null,
  errors?: string[] | null
}[] | null

sendText

messages.sendText Send a free-text message, which only works inside the 24-hour service window Risk: write

await corsair.wati.api.messages.sendText({ target: 'conv-1', text: 'Your order shipped.' });

Input

Name	Type	Required	Description
`target`	`string`	Yes	The contact wa_id or phone number.
`text`	`string`	Yes	—

Output

Name	Type	Required	Description
`message`	`object \| null`	No	—

message full type

{
  id?: string | null,
  message_id?: string | null,
  conversation_id?: string | null,
  wa_id?: string | null,
  message_type?: string | null,
  type?: string | null,
  event_type?: string | null,
  ticket_id?: string | null,
  owner?: boolean | null,
  operator_name?: string | null,
  local_message_id?: string | null,
  failed_detail?: string | null,
  text?: string | null,
  content?: any | null,
  status?: string | null,
  timestamp?: string | null,
  created?: string | null,
  from_me?: boolean | null,
  operator?: string | null,
  template_name?: string | null,
  media_url?: string | null
} | null

Segments

evaluate

segments.evaluate Evaluate a segment to see how many contacts match, without saving anything Risk: read

await corsair.wati.api.segments.evaluate({ groups: [{ operator: 'AND', conditions: [{ attribute: 'contact_status', operator: 'eq', value: 'active' }] }] });

Input

Name	Type	Required	Description
`groups`	`object[]`	Yes	The filters to run.
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

groups full type

{
  operator: AND | OR,
  conditions: {
    attribute: string,
    operator: string,
    value: string
  }[]
}[]

Output

Name	Type	Required	Description
`contacts`	`object[] \| null`	No	—
`total`	`number \| null`	No	—
`pageNumber`	`number \| null`	No	—
`pageSize`	`number \| null`	No	—
`hasNextPage`	`boolean \| null`	No	—
`count`	`number \| null`	No	—

contacts full type

{
  id?: string | null,
  wa_id?: string | null,
  name?: string | null,
  phone?: string | null,
  photo?: string | null,
  created?: string | null,
  last_updated?: string | null,
  contact_status?: string | null,
  source?: string | null,
  channel_id?: string | null,
  opted_in?: boolean | null,
  allow_broadcast?: boolean | null,
  allow_sms?: boolean | null,
  teams?: string[] | null,
  custom_params?: {
    name: string,
    value: string
  }[] | null
}[] | null

get

segments.get Read one saved segment Risk: read

await corsair.wati.api.segments.get({ segmentId: 'seg-1' });

Input

Name	Type	Required	Description
`segmentId`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`segmentId`	`string \| null`	No	—
`name`	`string \| null`	No	—
`tag`	`string \| null`	No	—
`description`	`string \| null`	No	—
`hitCount`	`number \| null`	No	—
`totalContactCount`	`number \| null`	No	—
`contact_count`	`number \| null`	No	—
`created`	`string \| null`	No	—
`lastUpdated`	`string \| null`	No	—

list

segments.list List saved segments Risk: read

await corsair.wati.api.segments.list({ page_number: 1 });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.

Output

Name	Type	Required	Description
`segments`	`object[] \| null`	No	—
`pageNumber`	`number \| null`	No	—
`pageSize`	`number \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

segments full type

{
  id?: string | null,
  segmentId?: string | null,
  name?: string | null,
  tag?: string | null,
  description?: string | null,
  hitCount?: number | null,
  totalContactCount?: number | null,
  contact_count?: number | null,
  created?: string | null,
  lastUpdated?: string | null
}[] | null

Templates

get

templates.get Read one message template and its components Risk: read

await corsair.wati.api.templates.get({ template_id: 'tpl-1' });

Input

Name	Type	Required	Description
`template_id`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`language`	`string \| null`	No	—
`status`	`string \| null`	No	APPROVED, PENDING, REJECTED and so on.
`category`	`string \| null`	No	—
`body`	`string \| null`	No	—
`custom_params`	`object[] \| null`	No	—
`language_option`	`object \| null`	No	—
`last_modified`	`string \| null`	No	—
`components`	`any[] \| null`	No	—
`created`	`string \| null`	No	—
`updated`	`string \| null`	No	—

custom_params full type

{
  name: string,
  value: string
}[] | null

language_option full type

{
  key?: string | null,
  value?: string | null,
  text?: string | null
} | null

list

templates.list List the message templates with their approval status Risk: read

await corsair.wati.api.templates.list({ page_number: 1, page_size: 20 });

Input

Name	Type	Required	Description
`page_number`	`number`	No	The page to return, 1-based. Defaults to 1.
`page_size`	`number`	No	Items per page, up to 100. Defaults to 20.
`channel`	`string`	No	Only templates on this sending channel.

Output

Name	Type	Required	Description
`templates`	`object[] \| null`	No	—
`messageTemplates`	`object[] \| null`	No	—
`message_templates`	`object[] \| null`	No	—
`page_number`	`number \| null`	No	—
`page_size`	`number \| null`	No	—
`total`	`number \| null`	No	—
`total_pages`	`number \| null`	No	—

templates full type

{
  id?: string | null,
  name?: string | null,
  language?: string | null,
  status?: string | null,
  category?: string | null,
  body?: string | null,
  custom_params?: {
    name: string,
    value: string
  }[] | null,
  language_option?: {
    key?: string | null,
    value?: string | null,
    text?: string | null
  } | null,
  last_modified?: string | null,
  components?: any[] | null,
  created?: string | null,
  updated?: string | null
}[] | null

messageTemplates full type

{
  id?: string | null,
  name?: string | null,
  language?: string | null,
  status?: string | null,
  category?: string | null,
  body?: string | null,
  custom_params?: {
    name: string,
    value: string
  }[] | null,
  language_option?: {
    key?: string | null,
    value?: string | null,
    text?: string | null
  } | null,
  last_modified?: string | null,
  components?: any[] | null,
  created?: string | null,
  updated?: string | null
}[] | null

message_templates full type

{
  id?: string | null,
  name?: string | null,
  language?: string | null,
  status?: string | null,
  category?: string | null,
  body?: string | null,
  custom_params?: {
    name: string,
    value: string
  }[] | null,
  language_option?: {
    key?: string | null,
    value?: string | null,
    text?: string | null
  } | null,
  last_modified?: string | null,
  components?: any[] | null,
  created?: string | null,
  updated?: string | null
}[] | null

Webhooks

delete

webhooks.delete Delete a webhook subscription, which stops delivery to that URL Risk: destructive

await corsair.wati.api.webhooks.delete({ id: 'wh-1' });

Input

Name	Type	Required	Description
`id`	`string`	Yes	—

Output

Name	Type	Required	Description
`success`	`boolean \| null`	No	—
`id`	`string \| null`	No	—
`contact_id`	`string \| null`	No	—
`deleted`	`boolean \| null`	No	—
`cleanup_completed`	`boolean \| null`	No	—

get

webhooks.get Read one webhook subscription and its event list Risk: read

await corsair.wati.api.webhooks.get({ id: 'wh-1' });

Input

Name	Type	Required	Description
`id`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`url`	`string \| null`	No	—
`name`	`string \| null`	No	—
`phone_number`	`string \| null`	No	—
`event_types`	`string[] \| null`	No	—
`eventTypes`	`string[] \| null`	No	—
`status`	`string \| null`	No	Enabled, Disabled or Defective.
`created`	`string \| null`	No	—

list

webhooks.list List webhook subscriptions; creating one still needs the V2 route, which this plugin does not wrap Risk: read

await corsair.wati.api.webhooks.list({});

Input: empty object Output

Name	Type	Required	Description
`webhooks`	`object[] \| null`	No	—

webhooks full type

{
  id?: string | null,
  url?: string | null,
  name?: string | null,
  phone_number?: string | null,
  event_types?: string[] | null,
  eventTypes?: string[] | null,
  status?: string | null,
  created?: string | null
}[] | null

Overview

Plugins

WATI API reference

Account

credits

Broadcasts

get

list

recipients

Channels

list

Contacts

count

create

delete

get

list

Conversations

list

messages

Messages

sendFile

sendTemplate

sendText

Segments

evaluate

get

list

Templates

get

list

Webhooks

delete

get

list

​Account

​credits

​Broadcasts

​get

​list

​recipients

​Channels

​list

​Contacts

​count

​create

​delete

​get

​list

​Conversations

​list

​messages

​Messages

​sendFile

​sendTemplate

​sendText

​Segments

​evaluate

​get

​list

​Templates

​get

​list

​Webhooks

​delete

​get

​list

Account

credits

Broadcasts

get

list

recipients

Channels

list

Contacts

count

create

delete

get

list

Conversations

list

messages

Messages

sendFile

sendTemplate

sendText

Segments

evaluate

get

list

Templates

get

list

Webhooks

delete

get

list