Integrations / WhatsApp Business

WhatsApp Business

WhatsApp Business Cloud API (Meta Graph API): send text and template messages, mark messages as read, and look up message templates and phone numbers. Free-form text only works inside the 24-hour customer-service window; otherwise use an approved template.

7 actions API key 4 read3 write Calls graph.facebook.com

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "whatsapp" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

This toolkit uses a single credential and requests no scopes.

Actions

Get message templatereadwhatsapp.get_message_templateGet one message template by id, including its approval status.

Input	Type		Description
`template_id`	string	Required	Message template id
`fields`	string	Optional	Comma-separated fields, e.g. name,status,category,components

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.get_message_template",
  input: {
    "template_id": "<template_id>"
  },
});

Get phone number inforeadwhatsapp.get_phone_numberGet details of a WhatsApp Business phone number: display number, verified name, quality rating and optionally status or throughput.

Input	Type		Description
`phone_number_id`	string	Required	WhatsApp Business phone number id
`fields`	string	Optional	Comma-separated fields, e.g. status,throughput,name_status

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.get_phone_number",
  input: {
    "phone_number_id": "<phone_number_id>"
  },
});

List message templatesreadwhatsapp.list_message_templatesList message templates of a WhatsApp Business Account, optionally filtered by name or approval status (APPROVED, PENDING, REJECTED).

Input	Type		Description
`waba_id`	string	Required	WhatsApp Business Account id
`name`	string	Optional	Filter by template name
`status`	string	Optional	Filter by approval status
`limit`	integer	Optional	Maximum templates to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.list_message_templates",
  input: {
    "waba_id": "<waba_id>"
  },
});

List phone numbersreadwhatsapp.list_phone_numbersList all phone numbers registered to a WhatsApp Business Account, with quality ratings.

Input	Type		Description
`waba_id`	string	Required	WhatsApp Business Account id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.list_phone_numbers",
  input: {
    "waba_id": "<waba_id>"
  },
});

Mark message as readwritewhatsapp.mark_as_readMark an incoming WhatsApp message as read (shows blue ticks to the sender) using its message id from a webhook.

Input	Type		Description
`phone_number_id`	string	Required	WhatsApp Business phone number id that received the message
`message_id`	string	Required	Incoming message id (wamid...)

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.mark_as_read",
  input: {
    "phone_number_id": "<phone_number_id>",
    "message_id": "<message_id>"
  },
});

Send template messagewritewhatsapp.send_template_messageSend an approved message template to a WhatsApp user. Works outside the 24-hour window and is the only way to start a conversation with a user.

Input	Type		Description
`phone_number_id`	string	Required	WhatsApp Business phone number id that sends the message
`to`	string	Required	Recipient WhatsApp number in international format, digits only
`template_name`	string	Required	Name of an approved template, e.g. hello_world
`language_code`	string	Required	Template language code, e.g. en_US
`components`	array of object	Optional	Optional template components that fill variables, e.g. [{type:'body',parameters:[{type:'text',text:'Ada'}]}]

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.send_template_message",
  input: {
    "phone_number_id": "<phone_number_id>",
    "to": "<to>",
    "template_name": "<template_name>",
    "language_code": "<language_code>"
  },
});

Send text messagewritewhatsapp.send_text_messageSend a free-form text message to a WhatsApp user. Only delivered if the user wrote to the business in the last 24 hours (customer-service window); otherwise use send_template_message.

Input	Type		Description
`phone_number_id`	string	Required	WhatsApp Business phone number id that sends the message (not the phone number itself)
`to`	string	Required	Recipient WhatsApp number in international format, digits only, e.g. 15551234567
`body`	string	Required	Message text, up to 4096 characters
`preview_url`	boolean	Optional	Show a link preview if the text contains a URL

TypeScript

await setu.execute({
  userId: "user_1",
  action: "whatsapp.send_text_message",
  input: {
    "phone_number_id": "<phone_number_id>",
    "to": "<to>",
    "body": "<body>"
  },
});