Thực hiện cuộc gọi AI và quản lý Astra qua API

API có thể cấu hình và xuất bản Astra (tác nhân AI của bạn), kết nối một số điện thoại với nó, và cho phép nó thực hiện các cuộc gọi đi: POST /v1/api/calls sẽ khiến tác nhân đã xuất bản của bạn gọi đến một số điện thoại, giữ cuộc trò chuyện và ghi lại cuộc gọi — với bản ghi âm, bản chép lời và tóm tắt — trên dòng thời gian của liên hệ trong hộp thư đến của bạn, được tính phí bằng tín dụng AI chính xác như một cuộc gọi đến được AI trả lời.

Trước khi bắt đầu

• Khóa API của bạn cần có các phạm vi phù hợp — các chip trong Cài đặt → API nhà phát triển: Quản lý tác nhân AI (agent:manage) để cấu hình tác nhân và định tuyến số, và Thực hiện cuộc gọi AI (calls:place) cho các cuộc gọi đi. Các khóa truy cập đầy đủ bao gồm cả hai. Xem Lấy khóa API Ody của bạn.
• Các cuộc gọi đi yêu cầu một gói dịch vụ đang hoạt động, một tác nhân đã xuất bản và kích hoạt, và ít nhất một số điện thoại đang hoạt động trong không gian làm việc của bạn.
• Tín dụng hoạt động chính xác như bình thường: 100 tín dụng cho mỗi cuộc gọi được AI trả lời, các cuộc gọi dưới 15 giây miễn phí, và mỗi gói dịch vụ bao gồm 1.000 tín dụng mỗi tháng. Xem Tín dụng và cách sử dụng Astra.

Cấu hình và xuất bản tác nhân của bạn

GET /v1/api/agent trả về cấu hình của tác nhân cùng với mức sử dụng tín dụng trong chu kỳ hiện tại của bạn — tiện lợi để kiểm tra ngân sách trước khi thực hiện một loạt cuộc gọi. PATCH /v1/api/agent cập nhật nó: name, greeting, tone, voice, language, timezone, inHoursAction/offHoursAction (agent, voicemail, app, hoặc forward), enabled, và jobs. Chỉ các trường bạn gửi mới thay đổi, ngoại trừ jobs, sẽ được thay thế hoàn toàn khi được cung cấp:

curl -X PATCH https://api.ody.co/v1/api/agent \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "greeting": "Thanks for calling Acme Plumbing!",
    "tone": "Friendly",
    "jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
  }'

Các thay đổi được lưu dưới dạng bản nháp — cùng bản nháp bạn sẽ thấy trên màn hình tác nhân AI trong ứng dụng. Đẩy nó lên trực tiếp bằng cách:

curl -X POST https://api.ody.co/v1/api/agent/publish \
  -H "Authorization: Bearer ody_live_…"

Kết nối một số điện thoại với tác nhân

POST /v1/api/numbers/{number}/connect định tuyến một trong các số điện thoại của bạn đến tác nhân để nó trả lời các cuộc gọi đến (mã hóa URL ký tự + thành %2B):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
  -H "Authorization: Bearer ody_live_…"

Để định tuyến nó trở lại nhóm của bạn, hãy sử dụng …/disconnect với mode là app (gọi đến nhóm của bạn — mặc định), voicemail, hoặc forward (với một số forwardTo):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"app"}'

Thực hiện cuộc gọi AI đi

POST /v1/api/calls sẽ khiến tác nhân đã xuất bản của bạn gọi đi và giữ cuộc trò chuyện:

curl https://api.ody.co/v1/api/calls \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550199"}'

• to là bắt buộc (E.164). from là tùy chọn — Ody ưu tiên số điện thoại được kết nối với tác nhân của bạn, sau đó là số điện thoại đang hoạt động đầu tiên của bạn; truyền from để chọn một đường dây cụ thể mà bạn sở hữu.
• Các điểm đến quốc tế tuân theo các quy tắc gọi quốc tế thông thường của không gian làm việc của bạn — xem Gọi quốc tế và giới hạn.
• Khi cuộc gọi kết thúc, nó sẽ xuất hiện trên dòng thời gian của liên hệ trong hộp thư đến của bạn với bản ghi âm, bản chép lời và tóm tắt — cùng một thẻ "tác nhân AI đã xử lý cuộc gọi này" như một cuộc gọi AI đến.
• Thanh toán: 100 tín dụng khi cuộc gọi được trả lời, miễn phí dưới 15 giây — và một cuộc gọi không bao giờ được trả lời luôn miễn phí.

Bạn có thể tiếp quản bất cứ lúc nào

Mọi thứ được thực hiện thông qua API đều là trạng thái tài khoản thực của bạn — không phải là một môi trường thử nghiệm dành cho nhà phát triển riêng biệt. Tác nhân mà mã của bạn xuất bản là tác nhân trên màn hình Tác nhân AI; số điện thoại nó kết nối nằm trong Cài đặt → Số điện thoại; các cuộc gọi nó thực hiện sẽ đến hộp thư đến chung của bạn. Điều đó có nghĩa là bạn có thể can thiệp bất cứ khi nào bạn muốn: chỉnh sửa lời chào trong ứng dụng, tự trả lời trong một cuộc hội thoại, hoặc nhấp vào các chip định tuyến của một số điện thoại để gửi cuộc gọi trở lại nhóm của bạn — không cần API.

Từ một trợ lý AI (MCP)

Các trợ lý AI được kết nối có cùng quyền hạn như các công cụ MCP: get_agent, configure_agent (truyền publish: true để kích hoạt ngay lập tức), connect_agent_to_number, và place_call. Xem Kết nối các công cụ AI với MCP.

Chế độ thử nghiệm

Với khóa ody_test_…, POST /calls trả về một cuộc gọi mô phỏng (một ID sim_…, không có cuộc gọi nào được thực hiện, không sử dụng tín dụng) và POST /agent/publish được mô phỏng (cấu hình của bạn vẫn ở dạng bản nháp). Các bản nháp được lưu qua PATCH /agent là thật trên cả hai loại khóa. Xem Xây dựng an toàn với chế độ thử nghiệm.

Các bài viết liên quan

• Gặp gỡ Astra, lễ tân AI của bạn
• Tín dụng và cách sử dụng Astra
• Mua số điện thoại và đăng ký nhắn tin qua API
• Kết nối các công cụ AI với MCP