Handling Zalo OA API with Python wrapper

A simple API wrapper script serves as a straightforward API wrapper for the Zalo Official Account (OA), offering a user-friendly interface to efficiently manage users, access detailed user information, and facilitate message exchanges. It's perfect for automating your Zalo OA interactions and enhancing customer engagement.

Key Features

• ✅ User Management — Retrieve the full list of users who’ve interacted with your OA.

• 📇 User Info — Fetch comprehensive details about individual users.

• ✉️ Messaging — Support for sending both text and image messages.

• 📬 Message Retrieval — Pull inbound messages from your OA

Setup & Installation

1. Clone the repository:

git clone https://github.com/nh4ttruong/zalo-oa-api-wrapper.git
cd zalo-oa-api

2. Install Dependencies: Ensure you have Python 3.7+ and install required packages

pip install -r requirements.txt

Configuration

1. Obtain your Zalo OA Access Token

• Head to the Zalo API Explorer

• Choose OA Access Token and click Get Access Token

• Tick to allow Term of User and copy the generated Access Token

2. Create your .env file

ZALO_OA_ZALO_OA_ACCESS_TOKEN=your_token_here

3. Configure messaging behavior. In .env, set flags:

   • SEND_MESSAGE_TEXT, SEND_MESSAGE_WITH_IMAGE

   • SEND_ALL_USERS, SEND_USER_LIST

   • IMAGE_FILE_PATH, MESSAGE_CONTENT, or MESSAGE_FILE_PATH

Examples

Sending a text message to a specific user

To send a message to a specific user (e.g., user_id = "7186086631826132217"):

from dependencies.messages import *

# User ID of the recipient
user_id = "7186086631826132217"
message_text = "Hello, this is a test message"

# Send a text message to the specified user
send_text_message(ZALO_OA_ACCESS_TOKEN, user_id, message_text)

Sending an image message

from dependencies.messages import *
from dependencies.upload import *

# Specify the user ID(s) and message content
user_id = "7186086631826132217"
users = [{"user_id": user} for user in user_id.split(",")]
message_text = "Hello, here’s an image for you!"

# Upload the image and retrieve the attachment ID
attachment_id = upload_media(ZALO_OA_ACCESS_TOKEN, file_path=IMAGE_FILE_PATH, type="image")

# Send the message along with the image
send_message_to_users(ZALO_OA_ACCESS_TOKEN, users, message_text=message_text, image_file=IMAGE_FILE_PATH)

Broadcast messages to all users

from dependencies.messages import *
from dependencies.upload import *
from dependencies.users import *

# Check if all users should receive the message
if SEND_ALL_USERS == 'True':
    users = get_all_users(ZALO_OA_ACCESS_TOKEN)
else:
    # Use a comma-separated list of user IDs from SEND_USER_LIST in .env file
    users = [{"user_id": user.strip()} for user in SEND_USER_LIST.split(",")]

# Send text or image message based on configuration
if SEND_MESSAGE_TEXT == 'True':
    if SEND_MESSAGE_WITH_IMAGE == 'True':
        send_message_to_users(ZALO_OA_ACCESS_TOKEN, users, message_text=MESSAGE_CONTENT, image_file=IMAGE_FILE_PATH)
    else:
        send_message_to_users(ZALO_OA_ACCESS_TOKEN, users, message_text=MESSAGE_CONTENT)
elif SEND_MESSAGE_WITH_IMAGE == 'True':
    send_message_to_users(ZALO_OA_ACCESS_TOKEN, users, message_text=MESSAGE_CONTENT, image_file=IMAGE_FILE_PATH)
else:
    print("No message to send")

Summary

This lightweight Python wrapper simplifies interaction with the Zalo OA API—handling user retrieval, message sending (text/image), and message intake with ease. Ideal for building engagement pipelines, bots, or customer support tools.