OAuth తో API v2
Oblic API కొత్త వెర్షన్ వ్యక్తి అనుసంధానించిన కార్యస్థలంలో Oblic ప్రయాణాలు, విభాగాలు, సందేశాలతో పని చేస్తుంది. API కీలకు బదులుగా OAuth 2.1 యాక్సెస్ టోకెన్లను ఉపయోగించి ఆ వ్యక్తి పాత్రతో పనిచేస్తుంది. /external/v1 మీ API కీలతో కొనసాగుతుంది.
ఈ వెర్షన్ OpenAPI పత్రం external-v2.json; OpenAPI సూచన దానిని వెర్షన్ 2గా చూపుతుంది.
టోకెన్ పొందడం
API v2 ఎప్పుడూ API కీని స్వీకరించదు: పంపితే 401 API_KEY_NOT_ACCEPTED వస్తుంది. బదులుగా వ్యక్తి మీ యాప్ను తన కార్యస్థలానికి అనుసంధానిస్తారు; అక్కడ యాప్ వారి తరఫున పనిచేస్తుంది.
Oblic డిప్లాయ్మెంట్లో OAuth అధికార సర్వర్ ప్రారంభమై ఉండాలి, API v2 అనుమతించిన వనరుగా ఉండాలి, సంతకం కీలు, సమ్మతి పేజీ కాన్ఫిగర్ అయి ఉండాలి, మీ క్లయింట్ నమోదు కావాలి. సమీకరణకు ముందు Oblic సహాయంతో లభ్యత నిర్ధారించండి; ఉదాహరణ URLలు డిప్లాయ్మెంట్ కాన్ఫిగర్ అయిందనడానికి సాక్ష్యం కాదు.
- యాప్ను నమోదు చేయండి. Oblic సహాయానికి పేరు, దారిమళ్లింపు URIలు, అవసరమైన పరిధులు ఇచ్చి క్లయింట్ ID పొందండి. క్లయింట్లు పబ్లిక్: క్లయింట్ రహస్యం లేదు; ప్రతి అధికార ప్రక్రియ PKCE వాడుతుంది. సర్వర్ లేదా నేటివ్ యాప్ మాత్రమే API ఉపయోగించవచ్చు; టోకెన్ ఎండ్పాయింట్, API ఏ బ్రౌజర్ ఆరిజిన్నూ అనుమతించవు.
- వ్యక్తిని సైన్ ఇన్ చేయించండి. API v2 సూచించే
resource, సందేశాలు పంపేందుకుscope=read send, లేదా చదవడానికి మాత్రమేscope=readతో అధికార ఎండ్పాయింట్ తెరవండి. వ్యక్తి Oblicలో ప్రవేశించి కార్యస్థలం ఎంచుకుని పరిధులను ఆమోదిస్తారు. - కోడ్ మార్పిడి చేయండి: టోకెన్ ఎండ్పాయింట్లో అదే
resourceఇవ్వండి. - APIని కాల్ చేయండి:
Authorization: Bearer <access token>ఉపయోగించండి.
| అధికార సర్వర్ | https://api.oblic.app (మెటాడేటా /.well-known/oauth-authorization-serverలో) |
| అధికార ఎండ్పాయింట్ | https://api.oblic.app/oauth2/authorize |
| టోకెన్ ఎండ్పాయింట్ | https://api.oblic.app/oauth2/token |
| వనరు | https://api.oblic.app/external/v2 |
| PKCE | S256 మాత్రమే |
| యాక్సెస్ టోకెన్ | డిఫాల్ట్గా ఒక గంట చెల్లుతుంది |
| రిఫ్రెష్ టోకెన్ | ప్రతి వాడకంలో మారుతుంది; డిఫాల్ట్గా 30 రోజులు వాడకపోయినా, తొలి అనుసంధానం నుంచి 90 రోజులు గడిచినా ముగుస్తుంది |
కోడ్ మార్పిడి
curl -X POST https://api.oblic.app/oauth2/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d code=THE_CODE \
-d redirect_uri=https://app.example.com/callback \
-d code_verifier=YOUR_CODE_VERIFIER \
-d resource=https://api.oblic.app/external/v2
Oblic MCP సర్వర్ వంటి మరో వనరుకు ఇచ్చిన టోకెన్ ఇక్కడ పనిచేయదు. ఉపయోగించగల టోకెన్ లేని అభ్యర్థనకు 401, WWW-Authenticate హెడర్ వస్తాయి; అది వనరు మెటాడేటా https://api.oblic.app/.well-known/oauth-protected-resource/external/v2ను సూచిస్తుంది.
పరిధులు మరియు పాత్రలు
- పేరు
read- టైప్ చేయండి
- scope
- వివరణ
ఈ పరిధిని ఎల్లప్పుడూ అడగండి; ఇది లేని టోకెన్ తిరస్కరించబడుతుంది. కార్యస్థల ప్రయాణాలు, విభాగాలు, API ద్వారా పంపిన సందేశాలను చదవవచ్చు.
- పేరు
send- టైప్ చేయండి
- scope
- వివరణ
సంస్థ తరఫున ఇమెయిల్, SMS, WhatsApp పంపే అభ్యర్థనలను క్యూలో ఉంచడానికి అనుమతిస్తుంది; ప్రదాత డెలివరీ చేశారని అర్థం కాదు. ఆమోదానికి ముందు ఈ పరిధి వ్యక్తికి ప్రత్యేక వరుసలో కనిపిస్తుంది.
పరిధి వ్యక్తి పాత్రను మించదు; Oblic ప్రతి అభ్యర్థనలో పాత్రను తనిఖీ చేస్తుంది. పాత్రను తీసేసినా వ్యక్తిని సంస్థ నుంచి తొలగించినా టోకెన్ ప్రవేశం వెంటనే ఆగుతుంది.
- ప్రయాణాలు మరియు విభాగాలు వ్యక్తి ఎంచుకున్న కార్యస్థలానికి చెందినవి; అక్కడి ఏ పాత్ర అయినా చదవవచ్చు.
- సందేశాలు API ద్వారా పంపినప్పుడు API కీలాగే సంస్థ డిఫాల్ట్ కార్యస్థలానికి చెందుతాయి. పంపేందుకు
sendపరిధి, ఆ కార్యస్థలంలో Owner, Admin లేదా Editor పాత్ర అవసరం; చదవడానికి అక్కడి ఏ పాత్ర అయినా సరిపోతుంది.
API కీల కోసం సంస్థ పెట్టిన IP అనుమతి జాబితా టోకెన్కు వర్తించదు; మీ యాప్ సర్వర్ల నుంచి వాడబడుతూ వ్యక్తి పాత్ర, ఆమోదించిన పరిధులకే పరిమితమవుతుంది.
API ఎండ్పాయింట్లు
ప్రతి జవాబులో {"status": "success", "data": …, "errors": null}, లేదా లోపాలతో "status": "error" ఉంటుంది.
| పద్ధతి | మార్గం | పని |
|---|---|---|
GET | /external/v2/journeys | కార్యస్థల ప్రచారాలు, ఆటోమేషన్లు, WhatsApp బాట్లు, Journeysలో నిర్మించిన ప్రయాణాలు; ఇటీవల మారినవి ముందు |
GET | /external/v2/journeys/{id} | ఒక ప్రయాణం |
GET | /external/v2/segments | కార్యస్థల జాబితాలు, తరువాత డైనమిక్ విభాగాలు |
GET | /external/v2/segments/{id} | ఒక విభాగం |
POST | /external/v2/messages/email | ధృవీకరించిన పంపేవారి నుంచి ఇమెయిల్ పంపుతుంది |
POST | /external/v2/messages/sms | మీ DLT నమూనాల్లో ఒకదానికి సరిపడే SMS పంపుతుంది |
POST | /external/v2/messages/whatsapp | ఆమోదించిన WhatsApp నమూనా లేదా 24 గంటల్లో జవాబు పంపుతుంది |
GET | /external/v2/messages | API ద్వారా పంపిన సందేశాలు, కొత్తవి ముందు, v1 జాబితా పారామీటర్లతో |
GET | /external/v2/messages/{messageId} | API ద్వారా పంపిన సందేశం, దాని ఫలితం |
ప్రయాణాల జాబితా
- పేరు
offset- టైప్ చేయండి
- integer
- వివరణ
పేజీ ప్రారంభం; డిఫాల్ట్
0.
- పేరు
limit- టైప్ చేయండి
- integer
- వివరణ
ప్రయాణాల సంఖ్య 1 నుంచి 100; డిఫాల్ట్
50.
- పేరు
mode- టైప్ చేయండి
- string
- వివరణ
campaign,automation,bot, లేదా Journeysలో నిర్మించిన ప్రయాణానికిjourney.
- పేరు
status- టైప్ చేయండి
- string
- వివరణ
అనుమతించిన స్థితులు:
draft,scheduled,live,pausedలేదాdone.
- పేరు
search- టైప్ చేయండి
- string
- వివరణ
ప్రయాణం పేరులో కొంత భాగం.
పేజీ nextOffset తరువాతి పేజీ ప్రారంభాన్ని సూచిస్తుంది; చివరి పేజీలో null.
ప్రయాణాల జాబితా
curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
ప్రతిస్పందన
{
"status": "success",
"data": {
"journeys": [
{
"id": "CMP000R7ZM4Q2VXH00",
"mode": "campaign",
"name": "Weekly offer",
"status": "live",
"createdAt": "2026-10-01T09:30:00Z",
"updatedAt": "2026-10-12T14:05:00Z"
}
],
"nextOffset": null
},
"errors": null
}
సందేశం పంపడం
బాడీలు /external/v1/messages మాదిరిగానే ఉంటాయి. అభ్యర్థన క్యూలో చేరి సందేశం IDతో 202 వస్తుంది. 1 నుంచి 255 అక్షరాల అదే Idempotency-Key హెడర్ ఇచ్చి v1 పంపకాల మాదిరిగా సురక్షితంగా మళ్లీ ప్రయత్నించండి: అదే అభ్యర్థన మొదటి IDను ఇస్తుంది, మళ్లీ పంపదు; అదే కీతో వేరే సందేశానికి 409 IDEMPOTENCY_CONFLICT వస్తుంది. కీ యాప్కు సొంతం; మరో యాప్ లేదా API కీ అదే విలువ వాడితే తనదైన వేరే సందేశం పంపుతుంది.
ఇమెయిల్ పంపండి
curl -X POST https://api.oblic.app/external/v2/messages/email \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-4471-shipped' \
-d '{
"to": ["customer@example.com"],
"subject": "Your order has shipped",
"html": "<p>Your order 4471 is on its way.</p>"
}'
ప్రతిస్పందన
{
"status": "success",
"data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
"errors": null
}
ఫలితాన్ని GET /external/v2/messages/{messageId} ద్వారా చదవండి.
API లోపాలు
| HTTP స్థితి | లోపం కోడ్ | అర్థం |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | యాక్సెస్ టోకెన్ పంపలేదు |
| 401 | INVALID_ACCESS_TOKEN | టోకెన్ గడువు ముగిసింది, మరో వనరుది, read లేదు లేదా వ్యక్తి సంస్థను వదిలారు: రిఫ్రెష్ చేయండి లేదా మళ్లీ అనుసంధానించండి |
| 401 | API_KEY_NOT_ACCEPTED | API కీ పంపారు: /external/v1తో ఉపయోగించండి |
| 403 | INSUFFICIENT_SCOPE | అవసరమైన పరిధి లేదు; WWW-Authenticate దానిని చెబుతుంది: మళ్లీ అనుసంధానించి ఆమోదించండి |
| 403 | FORBIDDEN | వ్యక్తి పాత్ర అనుమతించదు |
| 403 | EMAIL_SUSPENDED | బౌన్స్ లేదా స్పామ్ ఫిర్యాదులతో ఖాతా ఇమెయిల్ నిలిపివేశారు, /external/v1 మాదిరిగా |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | పారామీటర్, హెడర్ లేదా బాడీ లేదు లేదా చదవలేము |
| 400 | ఫీల్డ్ పేరు, ఉదాహరణకు TO | బాడీలో ఫీల్డ్ చెల్లదు |
| 402 | INSUFFICIENT_BALANCE | మార్కెటింగ్ SMS లేదా WhatsAppకు చెల్లించే వాలెట్లో నిధులు అవసరం; ఖాళీ వాలెట్ కారణంగా సైన్-ఇన్ కోడ్లు, లావాదేవీ సందేశాలు, జవాబులు తిరస్కరించబడవు |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | కార్యస్థలంలో లేదు లేదా API ద్వారా పంపలేదు |
| 404 | NOT_FOUND | అటువంటి రూట్ లేదు |
| 405 | METHOD_NOT_ALLOWED | రూట్ అభ్యర్థన పద్ధతిని అంగీకరించదు; Allow అనుమతించిన పద్ధతులను తెలుపుతుంది |
| 415 | UNSUPPORTED_MEDIA_TYPE | బాడీని application/jsonగా పంపలేదు |
| 422 | UNVERIFIED_SENDER | ఇమెయిల్ పంపేవారు ధృవీకరించబడలేదు |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | ఖాతా గంట పరిమితి లేదా నెల కోటా దాటింది, /external/v1 మాదిరిగా; Retry-After మళ్లీ ప్రయత్నించే సమయాన్ని తెలుపుతుంది |
SMS లేదా WhatsApp కూడా /external/v1 మాదిరిగా నిర్దిష్ట కారణంతో తిరస్కరించవచ్చు: ఆమోదించని నమూనా, మార్కెటింగ్ నుంచి తప్పుకున్న నంబర్, అనుసంధానించని నంబర్ లేదా పరిమితి చేరడం; తరువాత ప్రయత్నం ఉపయోగకరమైతే Retry-After ఉంటుంది.