# pai-engagement

Part of **PAI**

# Platform for AI (PAI) User Engagement

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Schedules | Synchronous | API to create a scheduled reach plan for engaging and recalling churned users, with parameters for timing, recurrence, and billing type. |

## API Calling Modes

### Authentication
The primary authentication method is **Bearer Token**.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While other Alibaba Cloud authentication methods exist (e.g., AccessKey), Bearer Token is recommended for PAI User Engagement APIs based on documentation examples.

### Service Endpoint
The API uses region-agnostic global endpoints:

- China region: `https://api.aliyun.com/api/PaiPlugin/2022-01-12/CreateSchedule`
- International region: `https://api.alibabacloud.com/api/PaiPlugin/2022-01-12/CreateSchedule`

Both endpoints accept POST requests and follow the same request/response structure.

### Synchronous
This API operates synchronously:
1. Send a POST request with JSON payload to the endpoint
2. The server processes the request immediately
3. A full JSON response is returned in the same HTTP response
4. No polling or async result fetching is required

Include `Content-Type: application/json` in headers. All parameters are passed in the JSON body under a top-level `body` object.

## Parameter Reference

### Manage Schedules

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| body | object | false | — | — | The main entity of the request parameters. |
| EndTime | string | false | — | — | End time (UTC+8). |
| ExecuteTime | string | false | — | — | Execution time (UTC+8): If empty, execute immediately. If you set an execution time, set the recurrence (RepeatCycle). |
| GroupId | string | true | — | — | Group ID. For more information on how to get a group ID, see ListGroups. |
| Name | string | true | — | length 2-30 characters | Reach plan name. The length is 2 to 30 characters. It supports letters, numbers, Chinese characters, and underscores (_). |
| RepeatCycle | integer | false | — | — | Recurrence. Execute based on the recurrence and recurrence unit. |
| RepeatCycleUnit | integer | false | 0 | one of: 0, 1, 2, 3, 4 | Recurrence unit. If you specify an execution time (ExecuteTime), execute based on the recurrence unit. Possible values: 0: Never (default), 1: Hour, 2: Day, 3: Week, 4: Month. |
| RepeatTimes | integer | false | -1 | one of: -1, 0, N | Number of recurrences. Possible values: -1: No end time (default), 0: No recurrence, N: Stop after N recurrences. |
| SignName | string | false | — | — | Signature name. For more information on how to get a signature name, see ListSignatures. |
| SignatureId | string | false | — | — | Signature ID. For more information on how to get a signature ID, see ListSignatures. |
| TemplateCode | string | false | — | — | Template Code. For more information on how to get a template Code, see ListTemplates. |
| TemplateId | string | false | — | — | The ID or code of the template. For more information, see ListTemplates. |
| AISendStartDate | string | false | — | — | Smart send start time. |
| AISendEndDate | string | false | — | — | Smart send end time. |
| PaymentType | string | false | PayAsYouGo | one of: PayAsYouGo, Subscription, MixPay | Billing type (defaults to pay-as-you-go if empty). Values are as follows: PayAsYouGo: Pay-as-you-go, Subscription: Subscription, MixPay: Mixed payment. |

## Code Examples

### Create a Basic Engagement Schedule - curl - all

```bash
curl -X POST https://api.aliyun.com/api/PaiPlugin/2022-01-12/CreateSchedule \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "body": {
    "GroupId": "0****195-03e2-40bd-869d-b71cb302783e",
    "Name": "Growth-2021-0101",
    "ExecuteTime": "2020-01-01 12:00:00",
    "RepeatCycle": 0,
    "RepeatCycleUnit": 0,
    "RepeatTimes": -1,
    "TemplateCode": "SMS_123***",
    "SignatureId": "0a54e195-03e2-40bd-869d-b71cb302****",
    "SignName": "PAI",
    "PaymentType": "PayAsYouGo"
  }
}'
```

### Create a Recurring Daily Schedule - curl - all

```bash
curl -X POST https://api.alibabacloud.com/api/PaiPlugin/2022-01-12/CreateSchedule \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "body": {
    "GroupId": "group-12345",
    "Name": "DailyReminder",
    "ExecuteTime": "2024-12-01 09:00:00",
    "RepeatCycle": 1,
    "RepeatCycleUnit": 2,
    "RepeatTimes": -1,
    "TemplateCode": "SMS_DAILY",
    "SignatureId": "sig-67890",
    "SignName": "MyApp",
    "PaymentType": "PayAsYouGo"
  }
}'
```

### Create a One-Time Immediate Schedule - curl - all

```bash
curl -X POST https://api.aliyun.com/api/PaiPlugin/2022-01-12/CreateSchedule \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "body": {
    "GroupId": "group-abcde",
    "Name": "UrgentAlert",
    "ExecuteTime": "",
    "RepeatCycle": 0,
    "RepeatCycleUnit": 0,
    "RepeatTimes": 0,
    "TemplateCode": "SMS_ALERT",
    "SignatureId": "sig-alert",
    "SignName": "AlertSystem",
    "PaymentType": "PayAsYouGo"
  }
}'
```

### Create a Monthly Subscription-Based Campaign - curl - all

```bash
curl -X POST https://api.alibabacloud.com/api/PaiPlugin/2022-01-12/CreateSchedule \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "body": {
    "GroupId": "premium-users",
    "Name": "MonthlyNewsletter",
    "ExecuteTime": "2024-12-01 10:00:00",
    "RepeatCycle": 1,
    "RepeatCycleUnit": 4,
    "RepeatTimes": 12,
    "TemplateCode": "EMAIL_NEWS",
    "SignatureId": "sig-news",
    "SignName": "NewsCo",
    "PaymentType": "Subscription"
  }
}'
```

## Response Format

```json
{
  "Data": {
    "CreatedTime": "2020-01-01 12:00:00",
    "EndTime": "2020-01-01",
    "ExecuteTime": "2020-01-01 12:00:00",
    "GroupId": "0****195-03e2-40bd-869d-b71cb302783e",
    "Id": "0a54****-03e2-40bd-869d-b71cb302783e",
    "Name": "Growth-2021-0101",
    "RepeatCycle": 0,
    "RepeatCycleUnit": 0,
    "RepeatTimes": -1,
    "SignName": "PAI",
    "SignatureId": "0a54e195-03e2-40bd-869d-b71cb302****",
    "Status": 0,
    "TemplateCode": "SMS_123***",
    "TemplateId": "0a54e***-03e2-40bd-869d-b71cb30*****",
    "UpdatedTime": "2020-01-01 12:00:00"
  },
  "ErrorCode": 0,
  "ErrorMessage": "OK",
  "RequestId": "f8651828-609d-4de8-ab49-ab781d7fd85****"
}
```

**Key Fields**:
- `Data.Id` — Unique identifier of the created schedule
- `Data.Name` — Name of the reach plan
- `Data.Status` — Current status (0 typically means active/successful)
- `Data.CreatedTime` — Timestamp when the schedule was created
- `Data.UpdatedTime` — Timestamp of last modification
- `ErrorCode` — 0 indicates success; non-zero indicates error
- `ErrorMessage` — Human-readable error message (or "OK" on success)
- `RequestId` — Unique ID for troubleshooting the request

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Invalid request format or missing required parameters. | Validate that all required fields (GroupId, Name) are present and correctly formatted. Check parameter constraints (e.g., Name length). |
| 403 | Access denied due to insufficient permissions or invalid API key. | Verify that your `DASHSCOPE_API_KEY` is valid and has permissions for PAI User Engagement APIs. |
| 429 | Too many requests; rate limit exceeded. | Implement exponential backoff and retry. Reduce request frequency. |
| 500 | Internal server error occurred during processing. | Retry the request after a short delay. If persistent, contact support with the RequestId. |

## FAQ

Q: What is the difference between TemplateCode and TemplateId?
A: Both refer to message templates, but TemplateCode is a human-readable string (e.g., "SMS_123***") while TemplateId is a UUID. Use either based on what your template listing returns—both are accepted.

Q: Can I update or delete a schedule after creation?
A: The current API documentation only describes schedule creation. Update and delete operations may be available via other endpoints not covered in this skill; check the full PAI Plugin API reference.

Q: What time zone is used for ExecuteTime and EndTime?
A: All times are interpreted in **UTC+8** (China Standard Time), regardless of the API endpoint region.

Q: Why do I need both SignName and SignatureId?
A: SignName is for display purposes, while SignatureId is the actual identifier used by the system. Provide both if available; SignatureId is sufficient for delivery.

Q: How do I obtain GroupId, SignatureId, or TemplateId?
A: Use the respective listing APIs: `ListGroups`, `ListSignatures`, and `ListTemplates` (not part of this skill but documented in the PAI Plugin API catalog).

## Pricing & Billing

### Billing Model
Billing is **per request**. Each successful `CreateSchedule` call counts as one billable request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| standard | 0.001 / | 0.001 / |

### Free Tier
Monthly free quota of **100 calls**.

### Usage Limits
Maximum throughput of **100 QPS** (queries per second).

### Billing Notes
Charged per actual request count. Each API invocation is counted as one request, regardless of schedule complexity or recurrence settings.