Truy cập API #

API (Giao diện lập trình ứng dụng) là một cách để các hệ thống phần mềm khác nhau giao tiếp với nhau. API Your AI Connector cho phép bạn (hoặc nhà phát triển của bạn) tự động tạo liên hệ, gửi tin nhắn, quản lý danh sách và nhận tin nhắn đến từ các kênh tùy chỉnh — tất cả mà không cần sử dụng bảng điều khiển.

Tại sao nên sử dụng API? Nếu bạn muốn kết nối ứng dụng với một công cụ không có tích hợp sẵn hoặc bạn cần tự động hóa các tác vụ lặp đi lặp lại trên quy mô lớn, API chính là giải pháp.

Tạo Khóa API của bạn #

1. Trong thanh bên trái, nhấp vào Settings (biểu tượng bánh răng).
2. Trong thanh bên Settings, dưới nhóm Integrations, nhấp vào API Key.

3. Nếu bạn chưa có khóa, hãy nhấp vào Generate API key.
4. Nếu bạn đã có khóa, nó sẽ được hiển thị dưới dạng ẩn trong mục Your key. Nếu khóa của bạn hỗ trợ, hãy nhấp vào Show để hiển thị khóa, sau đó nhấp vào Copy để sao chép — bạn sẽ thấy một thông báo xác nhận xuất hiện.
5. Hãy lưu trữ khóa ở nơi an toàn — bạn sẽ cần nó cho mọi yêu cầu API.

Thành viên nhóm: khóa API thuộc về chủ sở hữu tài khoản, vì vậy nếu bạn đăng nhập với tư cách là thành viên nhóm được mời (bao gồm cả Quản trị viên), phần này sẽ hiển thị một ghi chú thay vì khóa. Hãy đăng nhập với tư cách là chủ sở hữu tài khoản để xem, sao chép hoặc tạo lại khóa — điều này cũng áp dụng cho các khóa có phạm vi.

Tìm ở đâu: API Key là một mục riêng trong Settings → Integrations, tách biệt với Webhooks. Nếu hướng dẫn hoặc đồng nghiệp bảo bạn tìm khóa trong “Webhooks”, hãy tìm ở mục bên cạnh.

URL Cơ sở #

Tất cả các yêu cầu API đều sử dụng địa chỉ web cơ sở sau:

https://api.youraiconnector.com/v1/

Xác thực #

Mỗi yêu cầu phải bao gồm khóa API của bạn để nền tảng biết đó là bạn. Cách đơn giản nhất là thêm nó vào cuối địa chỉ web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Bạn cũng có thể gửi khóa dưới dạng tiêu đề yêu cầu thay vì trong URL (được khuyến nghị cho môi trường production, để khóa không bị lưu trong nhật ký máy chủ):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Tất cả các yêu cầu phải sử dụng kết nối bảo mật (HTTPS). Các yêu cầu không bảo mật (HTTP) sẽ bị từ chối.

Bạn đang tìm hướng dẫn đầy đủ cho nhà phát triển? Trang này là phần giới thiệu nhanh bao gồm các thao tác phổ biến nhất. Để xem hướng dẫn từng bước đầy đủ — mọi tài nguyên, cùng với các ví dụ về cURL, JavaScript và Python — hãy xem Bắt đầu với API và Tài liệu tham khảo API.

Các Thao tác API Phổ biến #

Tạo một Liên hệ #

Yêu cầu:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Các trường bắt buộc: phoneNumber (kèm mã quốc gia) luôn là bắt buộc để tạo liên hệ. Chỉ địa chỉ email là không đủ — yêu cầu không có số điện thoại hợp lệ sẽ bị từ chối. Email là tùy chọn.

Phản hồi:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Lưu data.contactId — bạn sẽ cần nó cho lệnh gọi “Thêm liên hệ vào danh sách”.

Thêm liên hệ vào danh sách #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Tìm ID của danh sách trong ứng dụng tại mục Contacts → Lists, từ menu hàng của danh sách đó (Copy list ID).

Cập nhật Liên hệ #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Chỉ các trường bạn bao gồm mới bị thay đổi. Đây cũng là cách để tải hàng loạt các giá trị trường tùy chỉnh sau khi nhập — xem Trường tùy chỉnh, Hồ sơ khách hàng tiềm năng & Ghi chú. Chi tiết đầy đủ trong API Danh bạ.

Gửi tin nhắn (Kênh tùy chỉnh) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Nhận tin nhắn đến (Kênh tùy chỉnh) #

Chấp nhận tin nhắn từ các hệ thống bên ngoài dưới dạng kênh tùy chỉnh. Đây là cách các tích hợp như GoHighLevel gửi tin nhắn vào Your AI Connector. Xem Kênh tùy chỉnh để biết chi tiết đầy đủ.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Tổng quan về các thao tác khả dụng #

Giới hạn tốc độ #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Các phương pháp hay nhất #

• Lưu trữ khóa API của bạn một cách an toàn — sử dụng trình quản lý mật khẩu hoặc cấu hình phía máy chủ, tuyệt đối không để trong mã phía máy khách mà khách truy cập trình duyệt có thể đọc được.
• Luôn bao gồm mã quốc gia trong số điện thoại (+1 cho Mỹ, +44 cho Anh, +31 cho Hà Lan).
• Xử lý lỗi một cách khéo léo — kiểm tra mã trạng thái và đọc bất kỳ thông báo lỗi nào được trả về.
• Xử lý trùng lặp — số điện thoại trùng lặp sẽ trả về { "success": false, "error_code": 409 } thay vì một liên hệ mới. Hãy tra cứu liên hệ trước nếu bạn cần làm việc với nó.
• Kiểm tra với tập dữ liệu nhỏ trước khi thực hiện các thao tác hàng loạt.

Phản hồi lỗi #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Các bước tiếp theo #

• Webhooks — nhận thông báo thời gian thực từ ứng dụng (một phần riêng biệt với khóa API của bạn).
• Kết nối Trợ lý AI (MCP) — sử dụng cùng một khóa API để cho phép Claude điều khiển tài khoản của bạn.
• Facebook Lead Forms — sử dụng API với các nền tảng tự động hóa để thu thập khách hàng tiềm năng.
• Tích hợp GoHighLevel — một ví dụ về tích hợp API hai chiều đầy đủ.