API బ్లాక్ - మీ చాట్‌బాట్ ఫ్లో నుండి బాహ్య APIలను కాల్ చేయండి

అవలోకనం

API బ్లాక్ మీ చాట్‌బాట్‌కు కన్వర్సేషన్ మధ్యలో ఏదైనా బాహ్య REST APIని కాల్ చేయడానికి, ప్రతిస్పందనను క్యాప్చర్ చేయడానికి మరియు విజయం లేదా వైఫల్యం ఆధారంగా ఫ్లోను రూట్ చేయడానికి అనుమతిస్తుంది. మీ డేటాబేస్‌లో ఆర్డర్‌లను చూడటానికి, OTPలను వెరిఫై చేయడానికి, షిప్‌మెంట్ స్థితిని ఫెచ్ చేయడానికి, అకౌంట్ బ్యాలెన్స్‌లను తనిఖీ చేయడానికి, లేదా HTTP ఎండ్‌పాయింట్‌ను బహిర్గతం చేసే ఏ సిస్టమ్‌ను అయినా ఇంటిగ్రేట్ చేయడానికి దీన్ని ఉపయోగించండి.

బాట్ API బ్లాక్‌ను చేరుకున్నప్పుడు, అది కాన్ఫిగర్ చేయబడిన HTTP అభ్యర్థనను పంపి, ప్రతిస్పందన కోసం వేచి ఉండి, JSON లేదా XML బాడీ నుండి ఫీల్డ్‌లను వేరియబుల్స్‌లోకి సంగ్రహించి, ఆపై విజయ శాఖ (HTTP 2xx/3xx) లేదా వైఫల్య శాఖ (HTTP 4xx/5xx)ను అనుసరిస్తుంది. ఫ్లోలోని తదుపరి బ్లాక్‌లు సందేశాలు, షరతులు, లేదా తదుపరి API కాల్‌లలో సంగ్రహించిన వేరియబుల్స్‌ను ఉపయోగించవచ్చు.

దీన్ని ఎక్కడ కనుగొనాలి

1. Studioలో మీ చాట్‌బాట్‌ను తెరవండి
2. ఎడమ సైడ్‌బార్ నుండి API బ్లాక్‌ను క్యాన్వాస్‌పైకి డ్రాగ్ చేయండి
3. ఏదైనా మునుపటి బ్లాక్ నుండి దాన్ని కనెక్ట్ చేయండి
4. దాన్ని కాన్ఫిగర్ చేయడానికి బ్లాక్‌ను డబుల్-క్లిక్ చేయండి

API బ్లాక్‌కు రెండు అవుట్‌పుట్ కనెక్షన్‌లు ఉన్నాయి: 2xx మరియు 3xx ప్రతిస్పందనల కోసం Success (పైన/డిఫాల్ట్), మరియు 4xx మరియు 5xx ప్రతిస్పందనల కోసం Failure (ద్వితీయ).

కాన్ఫిగరేషన్

స్టెప్ 1: అభ్యర్థన URL మరియు Methodను సెట్ చేయండి

ఫీల్డ్	వివరణ
URL	పూర్తి ఎండ్‌పాయింట్, ఉదాహరణకు https://api.example.com/orders/{order_id}
Method	HTTP వెర్బ్: GET, POST, PUT, PATCH, లేదా DELETE

{variable_name} సింటాక్స్ (సింగిల్ కర్లీ బ్రేసెస్)ను ఉపయోగించి ఫ్లోలో ముందుగా సంగ్రహించిన ఏదైనా వేరియబుల్‌ను మీరు చొప్పించవచ్చు. అభ్యర్థన పంపడానికి ముందు వేరియబుల్స్ రన్‌టైమ్‌లో పరిష్కరించబడతాయి.

స్టెప్ 2: క్వెరీ పారామితులను జోడించండి (ఐచ్ఛికం)

GET అభ్యర్థనల కోసం, URLకు key-value జతలను జోడించడానికి Query Parametersను ఉపయోగించండి. ప్రతి రో ఒక Key మరియు ఒక Value తీసుకుంటుంది. రెండు ఫీల్డ్‌లలో వేరియబుల్ సబ్‌స్టిట్యూషన్ పనిచేస్తుంది.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

స్టెప్ 3: Headersను కాన్ఫిగర్ చేయండి

Headers విభాగం కింద కస్టమ్ HTTP headersను జోడించండి. ప్రతి రో ఒక Key మరియు ఒక Value తీసుకుంటుంది.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

మీరు బాడీ ఫార్మాట్‌ను ఎంచుకున్నప్పుడు Content-Type ఆటో-గుర్తించబడుతుంది, కానీ మీరు దాన్ని ఓవర్‌రైడ్ చేయవచ్చు.

స్టెప్ 4: అథెంటికేషన్‌ను జోడించండి

API బ్లాక్ మూడు అథెంటికేషన్ మోడ్‌లకు మద్దతు ఇస్తుంది. మీ లక్ష్య APIకి సరిపోయే దాన్ని ఎంచుకోండి.

Auth రకం	ఫీల్డ్‌లు	ఇది ఎలా పంపబడుతుంది
Basic Auth	Username, Password	Authorization: Basic <base64>గా పంపబడుతుంది
Bearer Token	Bearer Token	Authorization: Bearer <token>గా పంపబడుతుంది
Custom Header	Header Name, Header Value	<Name>: <Value>గా పంపబడుతుంది (API కీలు, కస్టమ్ స్కీమ్‌ల కోసం)

గమనిక: x-api-key లేదా సారూప్యం ఉపయోగించే APIల కోసం, Custom Headerను ఎంచుకుని Nameను x-api-keyకు మరియు Valueను మీ కీకు సెట్ చేయండి. మీరు కీని ఒక వేరియబుల్‌లో నిల్వ చేసి దాన్ని {api_key}గా కూడా సూచించవచ్చు.

స్టెప్ 5: అభ్యర్థన బాడీని రూపొందించండి

POST, PUT, మరియు PATCH అభ్యర్థనల కోసం, Body విభాగంలో బాడీని కాన్ఫిగర్ చేయండి. ఫార్మాట్‌ను ఎంచుకోండి:

ఫార్మాట్	ఎప్పుడు ఉపయోగించాలి
JSON	చాలా ఆధునిక REST APIలు
XML	లెగసీ SOAP లేదా XML ఎండ్‌పాయింట్‌లు
None	బాడీ అవసరం లేదు (సాధారణంగా GET మరియు DELETEకు)

బాడీ ఎడిటర్‌లో రా JSON లేదా XMLను రాయండి. వేరియబుల్స్‌ను ఇన్‌లైన్‌గా చొప్పించవచ్చు:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

స్టెప్ 6: ప్రతిస్పందనను వేరియబుల్స్‌కు మ్యాప్ చేయండి

Save Response to Variables కింద, JSON ప్రతిస్పందన నుండి ఫీల్డ్‌లను ఫ్లో వేరియబుల్స్‌లోకి ఎలా సంగ్రహించాలో నిర్వచించండి.

JSON Path	వేరియబుల్ పేరు
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

మద్దతిచ్చే పాత్ సింటాక్స్:

• నెస్టెడ్ ఆబ్జెక్ట్‌ల కోసం Dot notation: result.user.email
• Array index: items[0].name
• Wildcard array extraction: items[*].id అన్ని IDలను అర్రేగా తిరిగి ఇస్తుంది
• Root field: status లేదా message

సంగ్రహించిన విలువలు అన్ని తదుపరి బ్లాక్‌లలో {variable_name}గా అందుబాటులో ఉంటాయి.

స్టెప్ 7: సబ్‌మిట్ చేసి సేవ్ చేయండి

బ్లాక్ మోడల్‌లో Submitపై క్లిక్ చేసి, ఆపై టాప్ బార్‌లో Save Changes ఉపయోగించి ఫ్లోను సేవ్ చేయండి.

ప్రతిస్పందన ఎలా నిర్వహించబడుతుంది

విజయ పాత్ (HTTP 2xx / 3xx)

1. Save Response to Variables నుండి వేరియబుల్స్ పూరించబడతాయి
2. ఫ్లో Success అవుట్‌పుట్ కనెక్షన్‌ను అనుసరిస్తుంది

వైఫల్య పాత్ (HTTP 4xx / 5xx)

1. లోప బాడీపై ఆధారపడి ప్రతిస్పందన వేరియబుల్స్ పూరించబడవచ్చు లేదా పూరించబడకపోవచ్చు
2. ఫ్లో Failure అవుట్‌పుట్ కనెక్షన్‌ను అనుసరిస్తుంది
3. ఫ్రెండ్లీ లోప సందేశాన్ని పంపడానికి లేదా మళ్లీ ప్రయత్నించడానికి ఈ శాఖను ఉపయోగించండి

టైమ్‌అవుట్

అభ్యర్థనలు 30 సెకన్ల తర్వాత టైమ్‌అవుట్ అవుతాయి. మీ API నెమ్మదిగా ఉంటే, పనిని రెండు స్టెప్‌లుగా విభజించడం లేదా వెబ్‌హుక్-ఆధారిత అసమకాలిక నమూనాను ఉపయోగించడం పరిగణించండి.

API Playgroundలో పరీక్షించడం

ప్రతి API బ్లాక్ కాల్ లాగ్ చేయబడుతుంది మరియు Studio లోపల API Playgroundలో అందుబాటులో ఉంటుంది. ప్రతి టెస్ట్ రన్ కోసం మీరు చూడవచ్చు:

• పూర్తిగా పరిష్కరించబడిన URL, method మరియు headers
• పంపబడిన అభ్యర్థన బాడీ
• స్వీకరించబడిన HTTP స్థితి కోడ్
• పూర్తి ప్రతిస్పందన బాడీ
• సంగ్రహించబడిన వేరియబుల్స్

ఫ్లోను షిప్ చేయడానికి ముందు టెంప్లేట్ వేరియబుల్స్, అథెంటికేషన్ మరియు JSON పాత్ మ్యాపింగ్‌లను డీబగ్ చేయడానికి playgroundను ఉపయోగించండి.

ఉత్తమ పద్ధతులు

• బ్లాక్ కాన్ఫిగ్‌లో కాకుండా వేరియబుల్స్‌లో సీక్రెట్‌లను నిల్వ చేయండి. environment-నిర్దిష్ట సెట్టింగ్‌ల నుండి API కీలను క్యాప్చర్ చేసి వాటిని వేరియబుల్స్ ద్వారా పాస్ చేయండి, తద్వారా అదే ఫ్లో staging మరియు productionలో పనిచేస్తుంది
• ఎల్లప్పుడూ Failure శాఖను కాన్ఫిగర్ చేయండి. API కాల్ విజయవంతం అవుతుందని ఎప్పుడూ అనుకోకండి. "We could not retrieve your order right now. Please try again later." వంటి ఫాల్‌బ్యాక్ సందేశాన్ని పంపండి
• అభ్యర్థన బాడీలను చిన్నగా ఉంచండి. APIకి అవసరమైతే తప్ప మొత్తం చాట్ హిస్టరీలను లేదా పెద్ద పేలోడ్‌లను పంపకండి
• ఉపయోగించడానికి ముందు ప్రతిస్పందన ఫీల్డ్‌లను ధృవీకరించండి. order_status తప్పిపోవచ్చు అయితే, దాన్ని సందేశంలో ఉపయోగించడానికి ముందు {order_status}ను తనిఖీ చేయడానికి API కాల్ తర్వాత Condition బ్లాక్‌ను జోడించండి
• వివరణాత్మక వేరియబుల్ పేర్లను ఉపయోగించండి. user_email val1 కంటే మెరుగైనది ఎందుకంటే Playgroundలో మరియు కన్వర్సేషన్ లాగ్‌లో డీబగ్ చేయడం సులభం
• JSON పంపేటప్పుడు Content-Typeను స్పష్టంగా సెట్ చేయండి, తద్వారా కఠినమైన APIలు అభ్యర్థనను అంగీకరిస్తాయి

సాధారణ వినియోగ సందర్భాలు

ఆర్డర్ లుకప్

కస్టమర్ ఆర్డర్ IDని అందిస్తారు, బాట్ మీ ఇ-కామర్స్ బ్యాకెండ్ నుండి స్థితిని ఫెచ్ చేస్తుంది.

• Method: GET
• URL: https://api.myshop.com/orders/{order_id}
• Auth: Bearer Token
• Response Map: data.statusను order_statusకు, data.tracking_urlను tracking_urlకు

OTP వెరిఫికేషన్

బాట్ 6-అంకెల కోడ్‌ను సేకరించి, మీ వెరిఫికేషన్ ఎండ్‌పాయింట్‌ను కాల్ చేసి, ఫలితం ఆధారంగా శాఖలుగా విభజిస్తుంది.

• Method: POST
• URL: https://api.myapp.com/verify-otp/
• Body: {"phone": "{phone}", "code": "{otp_code}"}
• Response Map: verifiedను otp_verifiedకు
• తదుపరి Condition బ్లాక్‌ను ఉపయోగించండి: {otp_verified} == true అయితే కొనసాగండి, లేకపోతే మళ్లీ అడగండి

CRM కాంటాక్ట్ సింక్

యూజర్ క్వాలిఫికేషన్ పూర్తి చేసినప్పుడు సేకరించిన కాంటాక్ట్ వివరాలను మీ CRMకు పుష్ చేయండి.

• Method: POST
• URL: https://api.crm.com/v1/contacts/
• Auth: Custom Header (x-api-key: {crm_key})
• Body: {"name": "{name}", "email": "{email}", "source": "chatbot"}

ట్రబుల్‌షూటింగ్

అభ్యర్థన 401 Unauthorizedతో విఫలమవుతుంది

1. auth రకం API ఆశించే దానితో సరిపోతుందని తనిఖీ చేయండి
2. Bearer టోకెన్‌ల కోసం, టోకెన్ ఫీల్డ్‌లో Bearer అనే పదాన్ని చేర్చకండి. బ్లాక్ దాన్ని ఆటోమేటిక్‌గా జోడిస్తుంది
3. Custom Header auth కోసం, header పేరు API డాక్‌లతో ఖచ్చితంగా సరిపోతుందని ధృవీకరించండి (కొన్ని APIల కోసం case-sensitive)
4. header పంపబడుతుందని నిర్ధారించడానికి API Playgroundలో అభ్యర్థనను తనిఖీ చేయండి

ప్రతిస్పందన నుండి వేరియబుల్స్ పూరించడం లేదు

1. API Playgroundను తెరిచి వాస్తవ ప్రతిస్పందన బాడీని తనిఖీ చేయండి
2. JSON పాత్ ప్రతిస్పందన నిర్మాణంతో సరిపోతుందని నిర్ధారించండి. పాత్‌లు case-sensitive
3. అర్రేల కోసం, ఒకే విలువ కోసం items[0].field లేదా అన్ని విలువల కోసం items[*].field ఉపయోగించండి
4. ప్రతిస్పందన XML అయితే, మీరు బాడీ ఫార్మాట్‌ను సరిగ్గా సెట్ చేశారని నిర్ధారించండి. JSON పాత్‌లు పార్స్ చేయబడిన XMLపై కూడా పనిచేస్తాయి

API పనిచేసినప్పటికీ ఫ్లో వైఫల్య శాఖను అనుసరిస్తుంది

1. API Playgroundలో HTTP స్థితి కోడ్‌ను తనిఖీ చేయండి. కొన్ని APIలు POSTపై 201 (Created)ను తిరిగి ఇస్తాయి, ఇది ఇంకా విజయం
2. API 200ను తిరిగి ఇచ్చినా బాడీలో లోపంతో ఉంటే, ప్రతిస్పందన ఫీల్డ్‌ను తనిఖీ చేయడానికి విజయ శాఖ తర్వాత Condition బ్లాక్‌ను ఉపయోగించండి

అభ్యర్థన టైమ్‌అవుట్ అవుతుంది

1. టైమ్‌అవుట్ 30 సెకన్లకు స్థిరంగా ఉంది. మీ API క్రమం తప్పకుండా ఎక్కువ సమయం తీసుకుంటే, API రియల్-టైమ్ చాట్‌కు సరిపోకపోవచ్చు
2. నెమ్మది పనిని బ్యాక్‌గ్రౌండ్ జాబ్‌కు తరలించి ఫలితం కోసం పోల్ చేయడం, లేదా సిద్ధంగా ఉన్నప్పుడు తెలియజేయడానికి వెబ్‌హుక్‌ను ఉపయోగించడం పరిగణించండి

టెంప్లేట్ వేరియబుల్స్ అభ్యర్థనలో రా {variable}గా కనిపిస్తాయి

1. ఫ్లోలో మునుపటి బ్లాక్ ద్వారా వేరియబుల్ సెట్ చేయబడిందని నిర్ధారించండి
2. వేరియబుల్ పేరు స్పెల్లింగ్‌ను తనిఖీ చేయండి (case-sensitive)
3. ఆ పాయింట్ వద్ద వాస్తవంగా ఏ వేరియబుల్స్ పూరించబడ్డాయో తనిఖీ చేయడానికి Conversation Logను ఉపయోగించండి

తదుపరి స్టెప్‌లు

• Webhook బ్లాక్ - ఫ్లోను ట్రిగర్ చేయడానికి లేదా పునఃప్రారంభించడానికి ఇన్‌బౌండ్ HTTP కాల్‌లను స్వీకరించండి
• Conversation End బ్లాక్ - రీస్టార్ట్ బటన్‌తో కన్వర్సేషన్‌లను ముగించండి
• Studio అవలోకనం - అన్ని బ్లాక్ రకాలు మరియు ఫ్లో బిల్డర్ ఫీచర్‌లను అన్వేషించండి