Oblic

OAuth తో API v2

Oblic API కొత్త వెర్షన్ వ్యక్తి అనుసంధానించిన కార్యస్థలంలో Oblic ప్రయాణాలు, విభాగాలు, సందేశాలతో పని చేస్తుంది. API కీలకు బదులుగా OAuth 2.1 యాక్సెస్ టోకెన్లను ఉపయోగించి ఆ వ్యక్తి పాత్రతో పనిచేస్తుంది. /external/v1 మీ API కీలతో కొనసాగుతుంది.


టోకెన్ పొందడం

API v2 ఎప్పుడూ API కీని స్వీకరించదు: పంపితే 401 API_KEY_NOT_ACCEPTED వస్తుంది. బదులుగా వ్యక్తి మీ యాప్‌ను తన కార్యస్థలానికి అనుసంధానిస్తారు; అక్కడ యాప్ వారి తరఫున పనిచేస్తుంది.

Oblic డిప్లాయ్‌మెంట్‌లో OAuth అధికార సర్వర్ ప్రారంభమై ఉండాలి, API v2 అనుమతించిన వనరుగా ఉండాలి, సంతకం కీలు, సమ్మతి పేజీ కాన్ఫిగర్ అయి ఉండాలి, మీ క్లయింట్ నమోదు కావాలి. సమీకరణకు ముందు Oblic సహాయంతో లభ్యత నిర్ధారించండి; ఉదాహరణ URLలు డిప్లాయ్‌మెంట్ కాన్ఫిగర్ అయిందనడానికి సాక్ష్యం కాదు.

  1. యాప్‌ను నమోదు చేయండి. Oblic సహాయానికి పేరు, దారిమళ్లింపు URIలు, అవసరమైన పరిధులు ఇచ్చి క్లయింట్ ID పొందండి. క్లయింట్లు పబ్లిక్: క్లయింట్ రహస్యం లేదు; ప్రతి అధికార ప్రక్రియ PKCE వాడుతుంది. సర్వర్ లేదా నేటివ్ యాప్ మాత్రమే API ఉపయోగించవచ్చు; టోకెన్ ఎండ్‌పాయింట్, API ఏ బ్రౌజర్ ఆరిజిన్‌నూ అనుమతించవు.
  2. వ్యక్తిని సైన్ ఇన్ చేయించండి. API v2 సూచించే resource, సందేశాలు పంపేందుకు scope=read send, లేదా చదవడానికి మాత్రమే scope=readతో అధికార ఎండ్‌పాయింట్ తెరవండి. వ్యక్తి Oblicలో ప్రవేశించి కార్యస్థలం ఎంచుకుని పరిధులను ఆమోదిస్తారు.
  3. కోడ్ మార్పిడి చేయండి: టోకెన్ ఎండ్‌పాయింట్‌లో అదే resource ఇవ్వండి.
  4. 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
PKCES256 మాత్రమే
యాక్సెస్ టోకెన్డిఫాల్ట్‌గా ఒక గంట చెల్లుతుంది
రిఫ్రెష్ టోకెన్ప్రతి వాడకంలో మారుతుంది; డిఫాల్ట్‌గా 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/messagesAPI ద్వారా పంపిన సందేశాలు, కొత్తవి ముందు, 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 స్థితిలోపం కోడ్అర్థం
401MISSING_ACCESS_TOKENయాక్సెస్ టోకెన్ పంపలేదు
401INVALID_ACCESS_TOKENటోకెన్ గడువు ముగిసింది, మరో వనరుది, read లేదు లేదా వ్యక్తి సంస్థను వదిలారు: రిఫ్రెష్ చేయండి లేదా మళ్లీ అనుసంధానించండి
401API_KEY_NOT_ACCEPTEDAPI కీ పంపారు: /external/v1తో ఉపయోగించండి
403INSUFFICIENT_SCOPEఅవసరమైన పరిధి లేదు; WWW-Authenticate దానిని చెబుతుంది: మళ్లీ అనుసంధానించి ఆమోదించండి
403FORBIDDENవ్యక్తి పాత్ర అనుమతించదు
403EMAIL_SUSPENDEDబౌన్స్ లేదా స్పామ్ ఫిర్యాదులతో ఖాతా ఇమెయిల్ నిలిపివేశారు, /external/v1 మాదిరిగా
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYపారామీటర్, హెడర్ లేదా బాడీ లేదు లేదా చదవలేము
400ఫీల్డ్ పేరు, ఉదాహరణకు TOబాడీలో ఫీల్డ్ చెల్లదు
402INSUFFICIENT_BALANCEమార్కెటింగ్ SMS లేదా WhatsAppకు చెల్లించే వాలెట్‌లో నిధులు అవసరం; ఖాళీ వాలెట్ కారణంగా సైన్-ఇన్ కోడ్‌లు, లావాదేవీ సందేశాలు, జవాబులు తిరస్కరించబడవు
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDకార్యస్థలంలో లేదు లేదా API ద్వారా పంపలేదు
404NOT_FOUNDఅటువంటి రూట్ లేదు
405METHOD_NOT_ALLOWEDరూట్ అభ్యర్థన పద్ధతిని అంగీకరించదు; Allow అనుమతించిన పద్ధతులను తెలుపుతుంది
415UNSUPPORTED_MEDIA_TYPEబాడీని application/jsonగా పంపలేదు
422UNVERIFIED_SENDERఇమెయిల్ పంపేవారు ధృవీకరించబడలేదు
429RATE_LIMITED, QUOTA_EXCEEDEDఖాతా గంట పరిమితి లేదా నెల కోటా దాటింది, /external/v1 మాదిరిగా; Retry-After మళ్లీ ప్రయత్నించే సమయాన్ని తెలుపుతుంది

SMS లేదా WhatsApp కూడా /external/v1 మాదిరిగా నిర్దిష్ట కారణంతో తిరస్కరించవచ్చు: ఆమోదించని నమూనా, మార్కెటింగ్ నుంచి తప్పుకున్న నంబర్, అనుసంధానించని నంబర్ లేదా పరిమితి చేరడం; తరువాత ప్రయత్నం ఉపయోగకరమైతే Retry-After ఉంటుంది.

ఈ పేజీ సహాయకరంగా ఉందా?