Let customers check the status of their Jira issues over WhatsApp, or create new issues straight from a WhatsApp conversation. Search by JQL, fetch by issue key, and post structured bug reports or feature requests into any Jira Cloud project.
Before following this guide, read the External API Request step foundation guide. It covers every field in the step interface so this guide can stay focused on Jira-specific values.
Jira REST API v3 uses Atlassian Document Format (ADF) for the description field, not a plain string. Sending plain text returns a 400 error. This guide shows the minimal ADF wrapper for plain-text descriptions so you can create issues without learning the full ADF spec.
Jira Cloud API tokens have a one-year expiry with no auto-renewal and no warning via the API. Set a calendar reminder to regenerate the token before it lapses, or your automation will silently start returning 401 errors.
Jira Cloud uses Basic Auth with your email address and an API token, not your password. Passwords are deprecated for API use.
acme.atlassian.net, your domain is
acme.Jira Cloud REST API v3: developer.atlassian.com
Jira Basic Auth encodes your email and API token together in Base64. The format is identical to Freshdesk, except here the password is the actual API token, not the letter X.
String to encode: your@email.com:YOUR_API_TOKEN
(email + colon + api token)
Base64 result: eW91ckBlbWFpbC5jb206QVBJX1RPS0VO
Authorization header:
Authorization: Basic eW91ckBlbWFpbC5jb206QVBJX1RPS0VO
Tools: any online Base64 encoder — input email:token, copy the output,
prepend 'Basic '.JQL (Jira Query Language) is how you filter issues. Pass it as a URL parameter to the stable v3 search endpoint. Store the customer's email or issue key as a variable first, then use it in the query.
| Field | Value | Notes |
|---|---|---|
| Select Method | GET | Reading issues, no body needed. |
| Request URL | https://YOUR-DOMAIN.atlassian.net/rest/api/3/search?jql=...&maxResults=5 | Replace YOUR-DOMAIN. The jql parameter is URL-encoded. maxResults limits the result set. |
| Authorization | Basic BASE64_OF_EMAIL_COLON_TOKEN | Compute once from email:api_token. Paste the full 'Basic ...' string. |
| Accept | application/json | Tells Jira to return JSON. Required. |
| Content-Type | application/json | Standard; include on all Jira calls. |
| What you want | JQL query string |
|---|---|
| Open issues by reporter email | project=SUPPORT AND reporter=priya@example.com AND status!=Done ORDER BY created DESC |
| Issues by issue key list | issuekey in (PROJ-1, PROJ-2, PROJ-3) |
| High-priority open bugs | project=PROJ AND issuetype=Bug AND priority=High AND status=Open |
| Issues assigned to a user | project=PROJ AND assignee=accountId:5b10a2844c20165700ede21g |
| Issues updated in last 7 days | project=PROJ AND updated >= -7d ORDER BY updated DESC |
URL-encode spaces as %20 and = as %3D when passing JQL as a GET parameter. Most HTTP clients do this automatically if you pass jql as a named parameter.
A successful Jira issue search response looks like this:
{
"total": 2,
"issues": [
{
"id": "10001",
"key": "SUPPORT-42",
"fields": {
"summary": "WhatsApp chatbot not responding after midnight",
"status": { "name": "In Progress" },
"priority": { "name": "High" },
"assignee": { "displayName": "Rahul Mehta",
"accountId": "5b10a2844c20165700ede21g" },
"created": "2026-06-20T10:30:00.000+0530"
}
}
]
}
Map: issues[0].key, issues[0].fields.summary,
issues[0].fields.status.name, issues[0].fields.priority.nameMap these paths in the External API Request step:
| Variable name | Response path | Example value |
|---|---|---|
| issue_key | issues[0].key | SUPPORT-42 |
| issue_summary | issues[0].fields.summary | Chatbot not responding |
| issue_status | issues[0].fields.status.name | In Progress |
| issue_priority | issues[0].fields.priority.name | High |
| issue_assignee | issues[0].fields.assignee.displayName | Rahul Mehta |
| issue_total | total | 2 |
issue_total tells the customer how many open issues exist. If total is 0 or issues is empty, add a conditions branch with a 'no open issues found' reply.
If the customer knows their issue key (SUPPORT-42), fetch it directly.
Ask them to type the key in WhatsApp, store it as
{{issue_key}}, then use it in the URL:
GET https://YOUR-DOMAIN.atlassian.net/rest/api/3/issue/{{issue_key}}
Authorization: Basic BASE64_OF_EMAIL_COLON_TOKEN
Accept: application/json
Response:
{{
"key": "SUPPORT-42",
"fields": {{
"summary": "Chatbot not responding after midnight",
"status": {{"name": "In Progress"}},
"priority": {{"name": "High"}},
"assignee": {{"displayName": "Rahul Mehta"}}
}}
}}
Map: key, fields.summary, fields.status.name, fields.assignee.displayNameWhen a customer reports a bug in WhatsApp, your bot can open a Jira issue automatically. The description must use Atlassian Document Format (ADF). Here is the minimal wrapper for plain text:
POST https://YOUR-DOMAIN.atlassian.net/rest/api/3/issue
Authorization: Basic BASE64_OF_EMAIL_COLON_TOKEN
Content-Type: application/json
Accept: application/json
Body:
{{
"fields": {{
"project": {{"key": "SUPPORT"}},
"summary": "WhatsApp: {{{{customer_issue_summary}}}}",
"issuetype": {{"name": "Bug"}},
"priority": {{"name": "Medium"}},
"description": {{
"type": "doc",
"version": 1,
"content": [{{
"type": "paragraph",
"content": [{{
"type": "text",
"text": "Customer WhatsApp message: {{{{customer_message}}}}"
}}]
}}]
}}
}}
}}
Response:
{{"id": "10002", "key": "SUPPORT-43", "self": "https://..."}}
Map: key -> new_issue_key
Bot replies: "Issue {{{{new_issue_key}}}} created. Our team will respond within 24 hours."The minimal ADF for a plain-text description is: {type: doc, version: 1, content: [{type: paragraph, content: [{type: text, text: YOUR TEXT HERE}]}]}. Sending a bare string for description returns a 400 Bad Request. Copy this wrapper exactly and substitute your text.
Customer: "What is the status of my support request?"
Bot asks: "Please share the email on your Atlassian account, or your issue key."
Customer: priya@example.com
Stored as {{customer_email}}.
External API Request step:
GET https://acme.atlassian.net/rest/api/3/search
?jql=project%3DSUPPORT%20AND%20reporter%3Dpriya%40example.com
%20AND%20status%21%3DDone%20ORDER%20BY%20created%20DESC
&maxResults=1
Authorization: Basic ZW1haWw6dG9rZW4=
Response mapped:
issue_key = "SUPPORT-42"
issue_summary = "Chatbot not responding after midnight"
issue_status = "In Progress"
issue_total = "2"
Conditions: if issue_total = 0 -> 'No open issues found for this email.'
Bot replies (if found):
"Hi Priya, I found 2 open issues on your account.
Most recent:
SUPPORT-42: Chatbot not responding after midnight
Status: In Progress
Reply KEY to check any other issue by its key number."| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Wrong email, wrong token, or wrong Base64 format | Recompute: Base64(your@email.com:api_token). Check that 'Basic ' prefix is present. Confirm you are using the API token, not your account password. |
| 404 on issue that exists | Account behind the token lacks Browse Projects permission | Ask your Jira admin to add the account to the project's permission scheme under Browse Projects. A 404 from Jira often means permission denied, not missing resource. |
| 400 on issue creation | Description not in ADF format | Wrap the description in the ADF structure shown above. Sending a plain string for description always returns 400 in v3. |
| 0 results from JQL search | Reporter email not matching Atlassian account | Jira matches the reporter field to the Atlassian account email. If the customer used a different email to raise the issue, the query returns 0. Try searching by issue key instead. |
| Token stopped working | API token expired after 1 year | Regenerate a new API token at id.atlassian.com and update the Base64 header value. |
| Username/key parameter not recognised | Using deprecated v2 user params in v3 | Jira v3 uses accountId, not username or key. For reporter/assignee filters in JQL, use the accountId value. |
Free trial, no credit card. And if you get stuck, we are the only platform in India that answers you live on WhatsApp.