YCloud

https://docs.ycloud.com/en
Admin
YCloud provides customer communication, marketing, sales, and support APIs and product docs, letting...
Tokens:483,719
Snippets:3,705
Trust Score:8.5
Update:18 hours ago
Show doc for...
Tokens:
Raw
### Example response for onboarding link creation

Source: https://docs.ycloud.com/en/partner-center/technical-development-partners/partner-direct-link-tp-lite

Example response from the API. The onboardingUrl is the hosted onboarding link. expiresAt is a Unix timestamp in milliseconds; the default link lifetime is two hours. Each link connects one customer to one WABA and cannot bind another WABA after successful binding.

```json
{
  "onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
  "expiresAt": 1893456000000
}
```

--------------------------------

### GET reachEstimate request example

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/max-price-integration-guide

Example request to the reach estimation endpoint with targetCountry=MX and dateInterval=L7D.

```http
GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D
```

--------------------------------

### whatsapp.business_account.updated webhook payload for auth-intl rate eligibility

Source: https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-business-account-updated-webhook-examples

Example webhook payload for the whatsapp.business_account.updated event with updateEvent AUTH_INTL_PRICE_ELIGIBILITY_UPDATE, listing eligible countries and their start times.

```json
{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}
```

--------------------------------

### Create onboarding link with curl

Source: https://docs.ycloud.com/en/partner-center/technical-development-partners/partner-direct-link-tp-lite

Use this curl command to create an onboarding link. The partnerCustomerId is required and should be a stable ID from your system. The onboardingType can be WHATSAPP_BUSINESS_PLATFORM or WHATSAPP_BUSINESS_APP. The locale is optional and defaults to en_US. Supported locales are en_US, zh_CN, es_ES, pt_BR, id_ID, and ru_RU; other values return HTTP 400.

```bash
curl -X POST 'https://api.ycloud.com/v2/partner/embeddedSignup/links' \
  -H 'X-API-Key: YOUR_YCLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerCustomerId": "customer_001",
    "onboardingType": "WHATSAPP_BUSINESS_PLATFORM",
    "locale": "en_US"
  }'
```

--------------------------------

### Calling settings response

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/manage-whatsapp-calls

Example JSON response returned by the GET request for Calling settings. The status field indicates whether Calling is enabled, and iconVisibility controls icon behavior.

```json
{
  "calling": {
    "id": "19213232132",
    "status": "ENABLED",
    "iconVisibility": "DEFAULT"
  }
}
```

--------------------------------

### Create Catalog Template - Request

Source: https://docs.ycloud.com/en/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples

Creates a catalog template with a body, footer, and a CATALOG button. The button text must be 'View catalog'. Requires an ecommerce catalog connected to the WhatsApp Business Account.

```bash
curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "intro_catalog_offer",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Now shop for your favourite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp!",
      "example": {
        "body_text": [
          [
            "100",
            "400",
            "3"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Best grocery deals on WhatsApp!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "CATALOG",
          "text": "View catalog"
        }
      ]
    }
  ]
}'
```

--------------------------------

### Create marketing template with video and CTA buttons

Source: https://docs.ycloud.com/en/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples

Creates a MARKETING template with a video header, body text with one variable, footer, and two buttons: one PHONE_NUMBER and one URL. The URL button can have at most one variable at the end of the URL. When using a dynamic URL button, provide a full URL in the example field. Templates are limited to one phone number button and two URL buttons.

```bash
curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday_more",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "VIDEO",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Click the URL bellow to see more about {{1}} campaign.",
      "example": {
        "body_text": [
          [
            "The Friday"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "FOOTER-TEXT"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Visit website",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": [
            "https://www.youtube.com/watch?v=zvI4cVGWJhM"
          ]
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Call us",
          "phone_number": "+447901614024"
        }
      ]
    }
  ]
}'
```

```json
{
  "wabaId": "WABA_ID",
  "name": "TEMPLATE_NAME",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING"
}
```

--------------------------------

### List groups with pagination using curl

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/manage-whatsapp-groups

Fetches a page of groups using the GET endpoint with limit and after parameters. The cursor is temporary; do not save it as a permanent ID. If invalid or expired, start again from the first page.

```bash
curl --get \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=NEXT_CURSOR"
```

--------------------------------

### Send reply buttons message via sendDirectly

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/best-practices/direct-send

Sends an interactive message with reply buttons using the sendDirectly endpoint. The interactive type is 'button' and includes two reply buttons with IDs and titles. Requires the same setup as other Direct Send examples.

```bash
curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "from": "BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": {
        "type": "text",
        "text": "Delivery update"
      },
      "body": {
        "text": "Your order A123456 is scheduled for delivery on September 15. Do you need help with this delivery?"
      },
      "footer": {
        "text": "Order A123456"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "delivery_help_A123456",
              "title": "I need help"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "delivery_ok_A123456",
              "title": "No help needed"
            }
          }
        ]
      }
    },
    "category": "utility",
    "useDirectSend": true,
    "ttlSeconds": 1800,
    "externalId": "order-A123456-delivery-reply"
  }'
```

--------------------------------

### Response example for profile update

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/manage-whatsapp-phone-numbers

Shows the response returned by profile and settings operations. Contains the updated resource fields.

```json
{
  "about": "Customer support and order updates",
  "email": "support@example.com",
  "vertical": "RETAIL",
  "websites": ["https://example.com"]
}
```

--------------------------------

### Send URL button message via sendDirectly

Source: https://docs.ycloud.com/en/api-reference/guides/whatsapp-platform/best-practices/direct-send

Sends an interactive message with a URL button using the sendDirectly endpoint. The interactive type is 'cta_url' and includes header, body, footer, and action parameters. Requires the same setup as other Direct Send examples.

```bash
curl --request POST \
  'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${YCLOUD_API_KEY}" \
  --data '{
    "from": "BUSINESS_PHONE_NUMBER",
    "to": "CUSTOMER_PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "cta_url",
      "header": {
        "type": "text",
        "text": "Order shipped"
      },
      "body": {
        "text": "Your order A123456 has shipped. View its latest delivery status below."
      },
      "footer": {
        "text": "Order A123456"
      },
      "action": {
        "name": "cta_url",
        "parameters": {
          "display_text": "Track order",
          "url": "https://example.com/orders/A123456"
        }
      }
    },
    "category": "utility",
    "useDirectSend": true,
    "ttlSeconds": 1800,
    "externalId": "order-A123456-shipped-url"
  }'
```

--------------------------------

### SDK Button HTML and JavaScript for YCloud Onboarding

Source: https://docs.ycloud.com/en/partner-center/technical-development-partners/partner-direct-link-tp-lite

Loads the YCloud SDK and sets up a button that fetches an onboarding link from your backend, then opens the signup window. Handles status updates, errors (including POPUP_BLOCKED), and window close events. Requires adding your page's origin to Allowed SDK origins and implementing the /api/ycloud/onboarding-link route.

```html
<script src="https://connect.ycloud.com/open/sdk/v1.js"></script>
<button id="yc-onboarding" type="button">Continue with Meta</button>
<p id="yc-status" role="status"></p>

<script>
  const status = document.getElementById('yc-status');
  document.getElementById('yc-onboarding').addEventListener('click', async function () {
    try {
      const response = await fetch('/api/ycloud/onboarding-link', { method: 'POST' });
      if (!response.ok) throw new Error('Link creation failed');
      const { onboardingUrl } = await response.json();
      YCloudOnboarding.open({
        onboardingUrl,
        onStatus: function (result) {
          status.textContent = result.state === 'CONNECTED'
            ? 'WhatsApp connected. Confirming with your server.'
            : 'Signup is not complete. Follow the instructions in the signup window.';
        },
        onError: function (error) {
          status.textContent = error.code === 'POPUP_BLOCKED'
            ? 'Allow popups for this site, then try again.'
            : 'Unable to open signup. Request a new link.';
        },
        onClose: function () {
          status.textContent = 'Signup window closed before a final result.';
        }
      });
    } catch {
      status.textContent = 'Unable to create a signup link. Please try again.';
    }
  });
</script>
```

--------------------------------

### Create WhatsApp marketing template with image and Quick Reply buttons

Source: https://docs.ycloud.com/en/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples

Use this curl command to create a WhatsApp marketing template with an image header, body text with one variable, footer text, and two Quick Reply buttons. The request must include your API key and WABA ID. The response returns the template resource with its review status.

```bash
curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, The Black Friday is coming!",
      "example": {
        "body_text": [
          [
            "Joe"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "FOOTER-TEXT"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Learn more"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe"
        }
      ]
    }
  ]
}'
```

--------------------------------

### GET Get Eval Summary

Source: https://docs.ycloud.com/en/documentation/meta-business-agent/test-and-evaluate

Retrieves evaluation summaries.

```APIDOC
## GET Get Eval Summary

### Description
Retrieves evaluation summaries. Summaries aggregate scores, highlights, and failure categories.

### Method
GET

### Endpoint
(Endpoint not explicitly provided in source)

### Parameters
(Not explicitly provided in source)

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
Returns evaluation summaries aggregating scores, highlights, and failure categories.

#### Response Example
(Not provided in source)

```

--------------------------------

### Create marketing template with GIF header

Source: https://docs.ycloud.com/en/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples

Creates a marketing WhatsApp template with a GIF header. The request includes the wabaId, template name, language, category, and components. The header component uses format GIF and provides an example header_url. The response returns the template resource with status PENDING.

```bash
curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "marketing_friday_more",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "GIF",
      "example": {
        "header_url": [
          "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "hello"
    }
  ]
}'
```

```json
{
  "wabaId": "WABA_ID",
  "name": "TEMPLATE_NAME",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING"
}
```

--------------------------------

### GET Get Connector Tool

Source: https://docs.ycloud.com/en/documentation/meta-business-agent/onboard-and-configure

Retrieves a specific tool by its ID.

```APIDOC
## GET /tools/{toolId}

### Description
Retrieves a specific tool by its ID.

### Method
GET

### Endpoint
/tools/{toolId}

### Parameters
#### Path Parameters
- **toolId** (string) - Required - The ID of the tool.

### Response
#### Success Response (200)
- **tool** (object) - The tool object.

#### Response Example
{
  "tool": {
    "name": "get_order",
    "description": "Gets an order",
    "request_definition": {
      "method": "GET",
      "path": "/orders"
    },
    "user_auth_required": false
  }
}
```

--------------------------------

### GET Get Eval Details

Source: https://docs.ycloud.com/en/documentation/meta-business-agent/test-and-evaluate

Retrieves detailed evaluation results for a run.

```APIDOC
## GET Get Eval Details

### Description
Retrieves detailed evaluation results. Detailed results include scores, turn labels, reasons, transcripts, and timestamps.

### Method
GET

### Endpoint
(Endpoint not explicitly provided in source)

### Parameters
(Not explicitly provided in source)

### Request Example
(Not provided in source)

### Response
#### Success Response (200)
Returns detailed evaluation results including scores, turn labels, reasons, transcripts, and timestamps.

#### Response Example
(Not provided in source)

```

--------------------------------

### POST /v2/partner/embeddedSignup/links

Source: https://docs.ycloud.com/en/partner-center/technical-development-partners/partner-direct-link-tp-lite

Creates an onboarding link for a customer to connect a WhatsApp Business Platform or Business App number. The link expires after two hours and can only be used once for binding.

```APIDOC
## POST /v2/partner/embeddedSignup/links

### Description
Creates an onboarding link for a customer to connect a WhatsApp Business Platform or Business App number. The link expires after two hours and can only be used once for binding.

### Method
POST

### Endpoint
https://api.ycloud.com/v2/partner/embeddedSignup/links

### Parameters
#### Request Body
- **partnerCustomerId** (string) - Required - A stable customer ID from your system. Avoid sensitive information. YCloud returns this ID in the successful binding webhook.
- **onboardingType** (string) - Required - Choose `WHATSAPP_BUSINESS_PLATFORM` for API-based messaging, or `WHATSAPP_BUSINESS_APP` for Business App coexistence.
- **locale** (string) - Optional - The hosted page language. Defaults to `en_US`. Supported values: `en_US`, `zh_CN`, `es_ES`, `pt_BR`, `id_ID`, `ru_RU`. Values are case-sensitive. Other values return HTTP 400.

### Request Example
```
curl -X POST 'https://api.ycloud.com/v2/partner/embeddedSignup/links' \
  -H 'X-API-Key: YOUR_YCLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerCustomerId": "customer_001",
    "onboardingType": "WHATSAPP_BUSINESS_PLATFORM",
    "locale": "en_US"
  }'
```

### Response
#### Success Response (200)
- **onboardingUrl** (string) - The URL for the customer to complete onboarding.
- **expiresAt** (number) - Expiry time as a Unix timestamp in milliseconds. Default link lifetime is two hours.

#### Response Example
```
{
  "onboardingUrl": "https://connect.ycloud.com/open/whatsapp/onboard#token=EXAMPLE_TOKEN",
  "expiresAt": 1893456000000
}
```

### Error Handling
- HTTP 400: Invalid locale value or other validation errors.
```

--------------------------------

### Create Order Details Template - Request

Source: https://docs.ycloud.com/en/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples

Creates an Order Details template with HEADER, BODY, FOOTER, and a BUTTON of type ORDER_DETAILS with text 'Review and Pay'. Must contain exactly one such button.

```bash
curl 'https://api.ycloud.com/v2/whatsapp/templates' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "wabaId": "{{WABA-ID}}",
  "name": "order_details_example",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Header text"
    },
    {
      "type": "BODY",
      "text": "Template Body text"
    },
    {
      "type": "FOOTER",
      "text": "Footer text"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "ORDER_DETAILS",
          "text": "Review and Pay"
        }
      ]
    }
  ]
}'
```

--------------------------------

### Check if WhatsApp is installed on Android (Kotlin)

Source: https://docs.ycloud.com/en/documentation/integrations/channels/verify/best-practices-for-verification/verification-via-whatsapp

Kotlin extension function to check if the WhatsApp or WhatsApp Business app is installed on the device. Uses PackageManager to check for the package names 'com.whatsapp' and 'com.whatsapp.w4b'. Returns true if either is installed.

```kotlin
fun PackageManager.isPackageInstalled(packageName: String): Boolean {
  return try {
    getPackageInfo(packageName, PackageManager.GET_ACTIVITIES)
    true
  } catch (e: NameNotFoundException) {
    false
  }
}

fun isWhatsAppInstalled : Boolean() {
    val whatsAppPackageName = "com.whatsapp"
    val whatsAppBusinessPackageName = "com.whatsapp.w4b"
    return getPackageManager().isPackageInstalled(whatsAppPackageName) || getPackageManager().isPackageInstalled(whatsAppBusinessPackageName)
}
```
Tokens:
Raw