Pangkalahatang-ideya at pagpapatunay ng API

Ang Ody REST API ay matatagpuan sa https://api.ody.co/v1/api at pinapatunayan ang bawat kahilingan gamit ang isang API key na ipinadala bilang isang Bearer token — gumawa ng isa sa Mga Setting → Developer API, pagkatapos ay tawagan ang mga endpoint sa ibaba.

Pagpapatunay

Ipadala ang iyong key sa Authorization header sa bawat kahilingan:

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• Ang mga key ay may dalawang mode: Ang mga ody_live_… key ay live, ang mga ody_test_… key ay kumikilos nang magkapareho ngunit ang pagpapadala ng mensahe ay simulated (naitala na may deliveryStatus: "simulated", hindi kailanman ipinadala). Tingnan ang Bumuo nang ligtas gamit ang test mode.
• Ang nawawala, hindi wasto, o binawi na key ay nagbabalik ng 401 unauthenticated.
• Ang isang key na pinaghihigpitan ng mga saklaw ay nagbabalik ng 403 permission_denied — na nagbabanggit ng nawawalang saklaw — kapag tumawag ito ng endpoint na nasa labas ng mga pahintulot nito.
• Ang bawat tawag ay tumatakbo na may mga pahintulot ng miyembro na lumikha ng key, sa loob lamang ng workspace na iyon.

Mga Endpoint

Paraan at path	Ano ang ginagawa nito	Kinakailangang saklaw
GET /v1/api/contacts	Ilista o hanapin ang mga contact (?q=, may pagination)	contacts:read
POST /v1/api/contacts	Gumawa ng contact	contacts:write
GET /v1/api/contacts/:id	Kunin ang buong detalye ng contact	contacts:read
PATCH /v1/api/contacts/:id	I-update ang contact (tanging ang mga ibinigay na field ang nagbabago)	contacts:write
DELETE /v1/api/contacts/:id	Burahin ang contact	contacts:write
GET /v1/api/conversations	Ilista ang mga pag-uusap (?status=open|done, may pagination)	conversations:read
GET /v1/api/conversations/:id	Kunin ang buong thread	conversations:read
PATCH /v1/api/conversations/:id	Itakda ang status — body {"status":"open"} o {"status":"done"}	conversations:write
POST /v1/api/messages	Magpadala ng SMS/MMS (sumusuporta sa Idempotency-Key)	messages:send
GET /v1/api/messages/search	Maghanap ng mga body ng mensahe at transcript (?q=)	conversations:read
GET /v1/api/calls	Ilista ang kasaysayan ng tawag at voicemail	conversations:read
POST /v1/api/calls	Maglagay ng outbound AI call — tatawag ang iyong na-publish na agent	calls:place
GET /v1/api/numbers	Ilista ang mga numero ng iyong workspace	numbers:read
GET /v1/api/numbers/available	Maghanap ng mga numerong mabibili mo (?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=)	numbers:manage
POST /v1/api/numbers	Bumili ng numero — sinisingil tulad ng isang in-app purchase (sumusuporta sa Idempotency-Key)	numbers:manage
POST /v1/api/numbers/:e164/connect at …/disconnect	I-ruta ang isang numero papunta o palayo sa iyong AI agent	agent:manage
GET /v1/api/messaging	Status ng pagpaparehistro ng 10DLC (step, canText)	numbers:manage
POST /v1/api/messaging/registration	Isumite ang iyong 10DLC business + campaign (may bayad)	numbers:manage
POST /v1/api/messaging/refresh	Muling suriin at isulong ang 10DLC carrier review	numbers:manage
GET/PATCH /v1/api/agent	Basahin o i-update ang config ng iyong AI agent (draft)	agent:manage
POST /v1/api/agent/publish	Ilagay ang iyong agent config nang live	agent:manage
GET /v1/api/webhook-events	Ilista ang mga uri ng webhook event na maaaring i-subscribe	webhooks:manage
GET/POST /v1/api/webhooks at /v1/api/webhooks/:id…	Pamahalaan ang mga outbound webhook endpoint	webhooks:manage
GET /v1/api/openapi.json	Ang OpenAPI 3.1 spec	wala

Ang mga listahan ng endpoint ay may pagination gamit ang ?limit= at ?cursor= — tingnan ang Pagination, idempotency, at paghawak ng error.

Mga Contact

POST /v1/api/contacts ay nangangailangan ng kahit isang identity field: firstName, lastName, company, isang numero ng telepono, o isang email. Ang mga telepono at email ay tumatanggap ng simpleng string ("phone": "+15125550123") o buong labeled arrays ("phones": [{"value": "+15125550123", "label": "work"}]). Sa PATCH, tanging ang mga field na ibinigay mo ang nagbabago; ang phones, emails, notes, properties, at tags ay ganap na pinapalitan kapag ibinigay.

Pagpapadala ng Mensahe

POST /v1/api/messages ay tumatanggap ng alinman sa isang umiiral na conversationId o isang numero ng telepono ng tatanggap sa to (format na E.164). Sa to, pipiliin ng Ody ang numero ng pagpapadala ng iyong workspace (o susundin ang isang from na pagmamay-ari mo), gagawa ng pag-uusap kung kinakailangan, at mag-thread ng mensahe. Magdagdag ng hanggang 10 publicly fetchable mediaUrls para sa MMS:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

Ang isang workspace na walang aktibong numero ng telepono ay makakakuha ng 409 failed_precondition. Ang mga retry na may parehong Idempotency-Key sa loob ng 24 na oras ay muling ipinapakita ang unang tugon sa halip na magpadala nang dalawang beses.

Mga Numero, Texting, AI Calls, at Iyong Agent

Kaya ring patakbuhin ng API ang isang linya ng telepono mula simula hanggang dulo: maghanap at bumili ng mga numero, magrehistro ng 10DLC texting, i-configure at i-publish ang iyong AI agent, i-ruta ang mga numero dito, at maglagay ng mga outbound AI call. Ang mga endpoint na ito ay gumagamit ng tatlong sarili nilang saklaw — numbers:manage (Bumili ng mga numero at 10DLC), calls:place (Maglagay ng mga AI call), at agent:manage (Pamahalaan ang AI agent) — at lahat ng ginagawa nila ay napupunta sa iyong account eksakto tulad ng kung ginawa mo ito sa app, na may parehong pagsingil at mga panuntunan. Tingnan ang Bumili ng mga numero at magrehistro ng texting sa pamamagitan ng API at Maglagay ng mga AI call at pamahalaan ang Astra sa pamamagitan ng API.

Mga Error, Request ID, at Rate Limit

Ang bawat error ay gumagamit ng isang pare-parehong envelope, at ang bawat tugon (tagumpay o error) ay nagdadala ng X-Request-Id header — banggitin ito kapag nakipag-ugnayan ka sa suporta:

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

Ang bawat key ay nakakakuha ng 600 kahilingan/minuto na may standard na RateLimit-* headers. Mga detalye sa Mga limitasyon ng rate ng API at pinakamahusay na kasanayan at Pagination, idempotency, at paghawak ng error.

Mga Kaugnay na Artikulo

• Kunin ang iyong Ody API key
• Tumanggap ng mga webhook at i-verify ang mga lagda
• Pagination, idempotency, at paghawak ng error
• Mabilis na pagsisimula ng SDK: TypeScript at Python