Communication

Whatsapp

Learn how to use Whatsapp with Composio

Overview

SLUG: WHATSAPP

Description

Enables interaction with customers through the WhatsApp Business API for messaging and automation.

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to whatsapp_business_management,whatsapp_business_messaging,business_management
bearer_token
string
generic_id
stringRequired
bearer_token
stringRequired
generic_id
stringRequired

Connecting to Whatsapp

Create an auth config

Use the dashboard to create an auth config for the Whatsapp toolkit. This allows you to connect multiple Whatsapp accounts to Composio for agents to use.

1

Select App

Navigate to Whatsapp.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Whatsapp Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4whatsapp_auth_config_id = "ac_YOUR_WHATSAPP_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11    connection_request = composio.connected_accounts.initiate(
12        user_id=user_id,
13        auth_config_id=auth_config_id,
14    )
15
16    print(
17        f"Visit this URL to authenticate Whatsapp: {connection_request.redirect_url}"
18    )
19
20    # This will wait for the auth flow to be completed
21    connection_request.wait_for_connection(timeout=15)
22    return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, whatsapp_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4whatsapp_auth_config_id = "ac_YOUR_WHATSAPP_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000"  # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10    # Replace this with a method to retrieve an API key from the user.
11    # Or supply your own.
12    user_api_key = input("[!] Enter API key")
13
14    connection_request = composio.connected_accounts.initiate(
15        user_id=user_id,
16        auth_config_id=auth_config_id,
17        config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18    )
19
20    # API Key authentication is immediate - no redirect needed
21    print(f"Successfully connected Whatsapp for user {user_id}")
22    print(f"Connection status: {connection_request.status}")
23    
24    return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, whatsapp_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Whatsapp toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["WHATSAPP"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17    completion = openai.chat.completions.create(
18        model="gpt-4o",
19        messages=[
20            {
21                "role": "user",
22                "content": task,  # Your task here!
23            },
24        ],
25        tools=tools,
26    )
27
28    # Handle Result from tool call
29    result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30    print(f"[!] Completion: {completion}")
31    print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Create message template

Description

Create a new message template for the whatsapp business account. templates must be approved by whatsapp before they can be used. templates are required for marketing messages and messages sent outside the 24-hour window.

Action Parameters

category
stringRequired
components
arrayRequired
language
stringRequired
name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete message template

Description

Delete a message template from the whatsapp business account. this permanently removes the template and it cannot be recovered. only delete templates that are no longer needed.

Action Parameters

template_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get business profile

Description

Get the business profile information for a whatsapp business phone number. this includes business details like description, address, website, and contact info.

Action Parameters

fields
stringDefaults to about,address,description,email,profile_picture_url,websites,vertical
phone_number_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get media

Description

Get information about uploaded media including a temporary download url. the download url is valid for 5 minutes and can be used to retrieve the actual media file. this is useful for downloading media that was sent to your whatsapp number.

Action Parameters

media_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get media info

Description

Get metadata about uploaded media without generating a download url. this is useful for checking file size, type, and hash without downloading the file. use get media if you need the actual download url.

Action Parameters

media_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get message templates

Description

Get all message templates for the whatsapp business account. templates are required for sending messages outside the 24-hour window and for marketing/utility messages.

Action Parameters

after
string
category
string
language
string
limit
integerDefaults to 25
name_or_content
string
status
string

Action Response

data
array
error
string
paging
object
successful
booleanRequired

Tool Name: Get phone number

Description

Get details of a specific phone number associated with a whatsapp business account.

Action Parameters

fields
stringDefaults to id,display_phone_number,verified_name,code_verification_status,quality_rating,platform_type,throughput,webhook_configuration,last_onboarded_time
phone_number_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get phone numbers

Description

Get all phone numbers associated with a whatsapp business account (waba).

Action Parameters

limit
integerDefaults to 25

Action Response

data
array
error
string
paging
object
successful
booleanRequired

Tool Name: Get template status

Description

Get the status and details of a specific message template. this is useful for checking if a template has been approved, rejected, or is still pending review.

Action Parameters

fields
stringDefaults to id,name,status,category,language
template_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send contacts

Description

Send contacts whatsapp number. note: the message will be delivered to the recipient only if they have initiated a conversation first.

Action Parameters

contacts
arrayRequired
phone_number_id
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send interactive buttons

Description

Send an interactive button message to a whatsapp number. button messages allow users to quickly respond by tapping up to 3 predefined buttons. perfect for yes/no questions, quick choices, or call-to-action scenarios. note: the message will be delivered to the recipient only if they have texted first.

Action Parameters

body_text
stringRequired
buttons
arrayRequired
footer_text
string
header_text
string
phone_number_id
stringRequired
reply_to_message_id
string
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send interactive list

Description

Send an interactive list message to a whatsapp number. list messages allow users to select from up to 10 options in a structured format. great for menus, catalogs, or choices. note: the message will be delivered to the recipient only if they have texted first.

Action Parameters

body_text
stringRequired
button_text
stringRequired
footer_text
string
header_text
string
phone_number_id
stringRequired
reply_to_message_id
string
sections
arrayRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send location

Description

Send a location message to a whatsapp number. note: the location will be shared with the recipient only if they have texted first.

Action Parameters

address
stringRequired
latitude
stringRequired
longitude
stringRequired
name
stringRequired
phone_number_id
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send media

Description

Send a media message to a whatsapp number. note: the media will be delivered to the recipient only if they have texted first.

Action Parameters

caption
string
link
stringRequired
media_type
stringRequired
phone_number_id
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send media by

Description

Send media using a media id from previously uploaded media. this is more efficient than sending media by url as the media is already on whatsapp servers. use upload media action first to get the media id. note: the media will be delivered to the recipient only if they have texted first.

Action Parameters

caption
string
filename
string
media_id
stringRequired
media_type
stringRequired
phone_number_id
stringRequired
reply_to_message_id
string
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send message

Description

Send a text message to a whatsapp number. note: the message will reflect on the recipient's phone number only if they have texted first.

Action Parameters

message_id
string
phone_number_id
stringRequired
preview_url
boolean
text
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send reply

Description

Send a reply to a specific message in a whatsapp conversation. this creates a contextual reply that shows which message you're responding to. note: the reply will be delivered to the recipient only if they have texted first.

Action Parameters

phone_number_id
stringRequired
preview_url
boolean
reply_to_message_id
stringRequired
text
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Send template message

Description

Send a template message to a whatsapp number.

Action Parameters

language_code
stringDefaults to en_US
phone_number_id
stringRequired
template_name
stringRequired
to_number
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Upload media

Description

Upload media files (images, videos, audio, documents, stickers) to whatsapp servers. the uploaded media gets a media id that can be used in send media or other messaging actions. supported formats: - images: jpeg, png (max 5mb) - videos: mp4, 3gpp (max 16mb) - audio: aac, m4a, amr, mp3, ogg (max 16mb) - documents: pdf, doc, docx, ppt, pptx, xls, xlsx (max 100mb) - stickers: webp (max 500kb, 512x512 pixels)

Action Parameters

file_to_upload
objectRequired
media_type
stringRequired
phone_number_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired