# Handling Zalo OA API with Python wrapper

A simple API wrapper script serves as a straightforward API wrapper for the [**Zalo Official Account (OA)**](https://oa.zalo.me/), 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:
    

```bash
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
    

```bash
pip install -r requirements.txt
```

## Configuration

1. Obtain your **Zalo OA Access Token**
    

* Head to the [Zalo API Explorer](https://developers.zalo.me/tools/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
    

```bash
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`
        

<div data-node-type="callout">
<div data-node-type="callout-emoji">💡</div>
<div data-node-type="callout-text">See the <a target="_self" rel="noopener noreferrer nofollow" href="https://developers.zalo.me/docs/official-account/bat-dau/kham-pha" style="pointer-events: none">API Reference</a> and Examples for details.</div>
</div>

## Examples

### Sending a text message to a specific user

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

```python
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

```python
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

```python
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.

%%[nh4ttruong]