# Instructions for connecting Zalo Cloud

{% hint style="info" %}
**Note** : eTelecom recommends that you use 2 separate applications for 2 sandbox and prod environments for convenience in API integration.
{% endhint %}

### **Step 1** : Access the [Zalo developers page](https://developers.zalo.me/) <a href="#buoc-1-truy-cap-vao-trang-zalo-developers" id="buoc-1-truy-cap-vao-trang-zalo-developers"></a>

### Step 2: Access the application you previously created <a href="#buoc-2-truy-cap-vao-ung-dung-ma-truoc-do-ban-da-tao" id="buoc-2-truy-cap-vao-ung-dung-ma-truoc-do-ban-da-tao"></a>

Select your Zalo account avatar icon as shown.

<figure><img src="/files/zDLPFe1yBmdjnzcYpR8q" alt=""><figcaption></figcaption></figure>

Go to the application you want to connect to eTelecom

<figure><img src="/files/QcxC3susxljRnMTzXNxr" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note** : If you don't have one, you can select " **Add new application** "
{% endhint %}

<figure><img src="/files/LP0muZNnYOUfmgtYOOgI" alt=""><figcaption></figcaption></figure>

Enter the required information. For details, please refer to this [document .](https://zalo.cloud/blog/huong-dan-tao-ung-dung-app-id-va-lien-ket-voi-zalo-oa-/kgua7vnkkvbyy88rma)

<figure><img src="/files/WA7f0eQAnp5wy5FZqXMs" alt=""><figcaption></figcaption></figure>

### Step 3: Proceed to "Domain authentication"

> The purpose of domain authentication is so that you can configure the webhook link provided by eTelecom.

After accessing the application -> Domain authentication -> Depending on the environment you are using, fill in the following domain information:

* **Sandbox** : <mark style="color:green;">**api-sandbox.etelecom.vn**</mark> and <mark style="color:green;">**etelecom.vn**</mark>
* **Prod** : <mark style="color:green;">**api.etelecom.vn**</mark> and <mark style="color:green;">**etelecom.vn**</mark>

<figure><img src="/files/oCN6LbLyyDftt4waohGi" alt=""><figcaption></figcaption></figure>

You select " **Verify now** " to proceed with authentication.

<figure><img src="/files/DIQhn6YqlZ1Kvn9fAf8p" alt=""><figcaption></figcaption></figure>

Select "Add meta tag to your website homepage" -> copy the meta tag in "Step 1" and send it to eTelecom.

<figure><img src="/files/Cbxhv9mQ5Kfykf4mxxdB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note** : The verification process may take up to 72 hours for Zalo to review. If the domain status is still Unverified, please select Verify again.
{% endhint %}

Successfully approved domains will be displayed in the "Verified Domain List" section.

<figure><img src="/files/BJuXQl48KyxMPb4uN59b" alt=""><figcaption></figcaption></figure>

### Step 4: Configure webhook

> Configuring "Webhook URL" will help eTelecom receive Zalo events returned to build reports, message sending history, ... accurately, serving your needs.

After [**successfully verifying the domain**](#step-3-proceed-to-domain-authentication) , you access " **Webhook " -> Copy the " OA Secret Key** " information and send it to eTelecom.

<figure><img src="/files/SisEHGBgCvZ2wpjUClsF" alt=""><figcaption></figcaption></figure>

eTelecom will update the "Secret Key" for the webhook and then notify you to change the " **Webhook URL** " information.

* **Sandbox**: <https://api-sandbox.etelecom.vn/v1/zalo/Callback>
* **Prod**: <https://api.etelecom.vn/v1/zalo/Callback>

<figure><img src="/files/0LtOb1b3nkwLMUlLGHwo" alt=""><figcaption></figcaption></figure>

In case you do not have " **OA Secret Key** " information, you proceed to change the "Webhook URL" according to the following information:

* **Sandbox**: <https://api-sandbox.etelecom.vn/v1/zalo/Callback>
* **Prod**: <https://api.etelecom.vn/v1/zalo/Callback>

After successful update, please provide eTelecom with the " **OA Secrect Key** " information.

<figure><img src="/files/rOpSF7JCyuvdKPiXpg5i" alt=""><figcaption></figcaption></figure>

After successful update, please provide eTelecom with the " **OA Secrect Key** " information.

<figure><img src="/files/W7g4nZo7R828ghlK3w2Y" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note** : In case your **"Update webhook url"** fails -> the system displays a message as shown, please " [**Proceed to verify domain**](#step-3-proceed-to-domain-authentication) " until the domain is displayed in the " **List of verified domains** " section.
{% endhint %}

<figure><img src="/files/445U3qiSGubjfZ7EVLug" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** If you reset or perform any operation that results in "OA Secret Key", please provide it to eTelecom.
{% endhint %}

In the " **Webhook event list** " section:

* If you use ZNS feature: you just need to enable " **Message received event** " and " **ZNS notification received user event** " as shown

<figure><img src="/files/YmqKDGC4ItPHBLLrubcG" alt=""><figcaption></figcaption></figure>

* If you use ZNS Journey: you need to enable the events " **Journey Expired Notification** " and " **Journey Charged Notification".**

<figure><img src="/files/AzazZ4sYsXIGopjbRFpN" alt=""><figcaption></figcaption></figure>

* **If you use ZCC** feature : you need to enable " **OA event sends call request to user / request expired** " and " **User event responds to call request from OA** "

<figure><img src="/files/ZczuG7Pm3MsUBdUzV6ok" alt=""><figcaption></figcaption></figure>

* To see **the list of interested people** , you need to enable the events " **User interested Official Account** " and " **User uninterested Official Account** ".

<figure><img src="/files/VUgKqEsH9gcCa9miptdC" alt=""><figcaption></figcaption></figure>

* To use the " **OA chat** " feature, you need to enable events related to " **Official Account** " and " **User**".

<figure><img src="/files/KvSIEaJD1YQmnSdwEz7s" alt=""><figcaption></figcaption></figure>

### Step 5: Set up the **path to request permission**

> The purpose of this step is for  eTelecom to have information to link your application with the eTelecom system.

{% hint style="info" %}
**Note** :

* In case the customer wants to " [Link Official Account](/api-etelecom-english/instructions-for-use/administration-page-for-cs.etelecom.md#link-zalo-official-account) " on [etelecom.vn](https://www.etelecom.vn/) , it is necessary to reset the permission request path in the "Official Account Callback Url" section according to the following information:
  * Prod environment: <https://api.etelecom.vn/v1/zalo/OAuth>
  * Sandbox Environment: <https://api-sandbox.etelecom.vn/v1/zalo/OAuth>
* In case customers want to integrate Zalo Cloud API into existing software, they can use their own Callback URL. The Callback URL is where processing is performed to receive the authorization code and the state returned after performing OA authorization for the App.
  {% endhint %}

<figure><img src="/files/MOKxkQF7Rh2cieMxZGoW" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.etelecom.vn/api-etelecom-english/api-integration/zalo-cloud/instructions-for-connecting-zalo-cloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.