WhatsApp API integration with Python

Prepare the environment

Install `requests`, create a HookMessage API key with the role required by the endpoint, and store secrets outside source control.

Environment

bash

pip install requests
export HOOKMESSAGE_BASE_URL=https://api.hookmessage.com
export HOOKMESSAGE_API_KEY=was_replace_with_your_key

Send a message with a timeout

Always set a network timeout. A timeout is an unknown result, not proof that the server rejected the message, so retry with the same idempotency key.

hookmessage.py

python

import os
import requests

def send_message(receiver_number: str, message: str, reference: str):
    response = requests.post(
        f"{os.environ['HOOKMESSAGE_BASE_URL']}/api/messages/send",
        headers={
            "x-api-key": os.environ["HOOKMESSAGE_API_KEY"],
            "content-type": "application/json",
            "idempotency-key": reference,
        },
        json={
            "receiver_number": receiver_number,
            "message": message,
            "source_system": "python-app",
            "source_reference": reference,
        },
        timeout=15,
    )

    payload = response.json()
    if not response.ok:
        raise RuntimeError(payload.get("message", "HookMessage request failed"))
    return payload

Connect it to your framework

Call the integration from a server-side service or background task, not directly from a template or browser script. Validate the authenticated user and business event before sending.

Django: call from a service and enqueue long-running work with your task system.
Flask: keep the key in server configuration and avoid blocking slow request handlers.
FastAPI: validate the request model and isolate the outbound client in a dependency or service.
Workers: persist the business reference so retries remain idempotent.

Diagnose failures safely

Log the HTTP status, HookMessage error code, source reference, and message ID when available. Do not log the API key, OTP code, or full message body.

Confirm the API key role matches the endpoint.
Confirm receiver numbers use international format.
Confirm paid sender IDs belong to the same workspace and key.
Check queue and sender health when a message remains processing.

Send a message with a timeout

Always set a network timeout. A timeout is an unknown result, not proof that the server rejected the message, so retry with the same idempotency key.

hookmessage.py

python

import os
import requests

def send_message(receiver_number: str, message: str, reference: str):
    response = requests.post(
        f"{os.environ['HOOKMESSAGE_BASE_URL']}/api/messages/send",
        headers={
            "x-api-key": os.environ["HOOKMESSAGE_API_KEY"],
            "content-type": "application/json",
            "idempotency-key": reference,
        },
        json={
            "receiver_number": receiver_number,
            "message": message,
            "source_system": "python-app",
            "source_reference": reference,
        },
        timeout=15,
    )

    payload = response.json()
    if not response.ok:
        raise RuntimeError(payload.get("message", "HookMessage request failed"))
    return payload

Connect it to your framework

Call the integration from a server-side service or background task, not directly from a template or browser script. Validate the authenticated user and business event before sending.

Django: call from a service and enqueue long-running work with your task system.

Flask: keep the key in server configuration and avoid blocking slow request handlers.

FastAPI: validate the request model and isolate the outbound client in a dependency or service.

Workers: persist the business reference so retries remain idempotent.

Diagnose failures safely

Log the HTTP status, HookMessage error code, source reference, and message ID when available. Do not log the API key, OTP code, or full message body.

Confirm the API key role matches the endpoint.

Confirm receiver numbers use international format.

Confirm paid sender IDs belong to the same workspace and key.

Check queue and sender health when a message remains processing.