Send and receive WhatsApp from Python

How do you receive messages in Python?

With two handlers on one route, in whatever framework you already use.

The GET handler answers Meta's verification. It reads hub.mode, hub.verify_token and hub.challenge from the query string, checks the token against your own, and returns the challenge as the raw body. Returning JSON here is the most common mistake, and it fails silently.

The POST handler receives events. Return 200 quickly and do the work afterwards, because Meta treats a slow response as a failure and will retry, which means handling the same message twice. Queue it, or hand it to a background task, rather than doing the processing inline.

Messages arrive with a wamid message id. Deduplicating on it is worth doing from the start, since retries are normal rather than exceptional.

How do you send?

One POST to the Cloud API messages endpoint for the phone number id, with a bearer token.

Both values come from the connection: the dashboard shows them, and get_api_credentials returns them if you would rather an assistant fetch them. Nothing about the call is specific to us, so any HTTP library works and the request looks exactly like Meta's own documentation.

What changes with timing is the body. Inside 24 hours of the customer's last message you send a text object. Outside it you send a template object naming an approved template and its language. A client that only knows the first shape works perfectly in testing and fails on the first overnight message, returning error 131047.

What does a production handler need beyond that?

Three things that are easy to skip and expensive to add later.

Deduplicate on the message id, because Meta retries. Verify the request signature if you are exposed publicly, since anyone who learns your URL can post to it otherwise. And branch on how long ago the contact last wrote, so the send path picks text or template without a human deciding.

None of these need a framework or a library. They are a set, a check and a comparison, and getting them in place before the first client is the difference between an integration that runs quietly and one that pages you.

Common mistakes

• Returning JSON from the verification GET instead of the raw challenge value.
• Processing inline before returning 200. Meta retries slow responses and you handle the message twice.
• Sending free text without checking the window. It returns 131047 and looks like nothing happened.

Frequently asked questions

Keep reading