#1864: Integrating Swarmica with an external Helpdesk

Отредактирована: сегодня

It is strongly recommended to configure integration in such a way that one system is primary and the other is secondary. This is necessary to avoid conflicts between systems and possible inconsistencies.

Integration with external systems can be implemented through webhooks on certain API endpoints.

For correct operation, both systems must store metadata of the entities of the external system. For example, the ID of a request in the external system. An example of integrating Swarmica with a third-party Helpdesk will be provided below.

Interaction scheme:

End user → external Helpdesk → API → Swarmica

The end user works only in the external Helpdesk and may not even be aware of the existence of Swarmica.

For such interaction, it is necessary to configure webhooks in the external Helpdesk that will send API requests to Swarmica depending on the events occurring in the external Helpdesk.

All API requests to Swarmica use Headers depending on the type of token.

For Bearer token:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer BEARER_TOKEN"
}

For API token:

{
  "Content-Type": "application/json",
  "Authorization": "Token API_TOKEN"
}

Interaction scenarios

Scenario 1: Creating a ticket in Swarmica

The external Helpdesk must have a webhook configured that, under certain conditions (for example, creating a request in the external Helpdesk), sends an API request to Swarmica to create a request.

API request parameters in Swarmica:

Endpoint: /api/tickets/

Method: POST

Payload:

{
  "subject": "test API ticket 11111",         # ticket subject
  "comment": "Comment 1",                     # problem description
  "ext_id": 12345,                            # ID of the request in the external Helpdesk
  "requester_email": "jdoe@example.tld",      # applicant's email
  "idempotency_key": "12345678"               # idempotency key
}

A successful request returns a response similar to this:

response_text='{"id":56,"subject":"test API ticket 11111","ext_id":12345,"requester":"j9m7sRnuAHFcWD9Q","assignee":null,"group":null,"status":"OPEN","until":null,"priority":"normal","replies":1,"reopens":0,"created_at":"2026-08-20T08:10:00.432419Z","resolved_at":null,"updated_at":"2026-08-20T08:10:00.547359Z","is_fcr":false,"satisfaction_score":"UNOFFERED","custom_fields":[{"uid":"1KZHEyoEPQhaD0Ii","name":{"en":"Can grant access to environment","ru":"Могу дать доступ, если надо"},"mandatory_for":[],"value":null},{"uid":"ouVl3K0SUvirO-LR","name":{"en":"link","ru":"ссылка"},"mandatory_for":[],"value":null},{"uid":"UJB6rUrOwq0Oarjt","name":{"en":"text 1","ru":"текст 1"},"mandatory_for":[],"value":null},{"uid":"Kd6ln4rmOpbVcmxd","name":{"en":"text 2","ru":"текст 2"},"mandatory_for":[],"value":null}],"platform":null,"product":null,"version":null,"edition":null,"ticketsla":{"ticket":56,"policy":"kjmiYksE1_KY0G-2","schedule":"H51qT1YSgKkq5T48","first_response_time":{"target":"08:00:00.000000","diff":"07:59:59.920475","value":"00:00:00.079525","is_running":true,"out_of_schedule":false,"breach_idx":2.761284722208046e-06},"full_resolution_time":null,"next_response_time":null,"agent_update_time":null,"support_resolution_time":null,"customer_wait_time":null,"sla_breach_idx":2.761284722208046e-06},"comment":null,"license":null,"organization":null,"ticket_session":null,"forked_from":null,"tz_offset_minutes":0,"locked":false,"time_spent":null,"time_estimate":null,"article_not_needed":false,"article_links":0,"channels":[{"uid":"4tzzvd-_6OBOggZB","channel":"jEcHl-ZdUbBhSLnD","channel_type":"EMAIL","name":"main mail channel","identity":"AftZP8cnT2IZmnxM","ext_id":"user@email.tld","muted":false}],"source":"jEcHl-ZdUbBhSLnD","last_reply_by":"7Cf0WL7sanTeMRIF","last_reply_at":"2026-08-20T08:10:00.536283Z","issue_count":0,"last_comment_by":"7Cf0WL7sanTeMRIF","last_comment_at":"2026-08-20T08:10:00.536283Z","cc":[],"issues":[],"is_external":false,"parent_ticket":null,"locale":"ru"}'

From this response, you need to take the ID of the request in the target system (Swarmica) and save it for further interactions.

Scenario 2: Updating an existing ticket via API

Similarly to the previous scenario, it is necessary to configure webhooks that will update the ticket in Swarmica depending on the events in the original ticket. For example, we will take the following events:

Adding a comment to a request on the side of the external Helpdesk

API request parameters in Swarmica:

Endpoint: /api/tickets/{ID}/comments

Here, instead of ID, you need to insert the ID of the request in Swarmica, obtained when creating the request (Scenario 1)

Method: POST

Payload:

{
  "body": "added comment",
  "public": true
}

Example response:

{"id":205,"ext_id":null,"ticket":56,"author":"7Cf0WL7sanTeMRIF","is_staff":true,"created_at":"2026-08-20T08:59:28.262866Z","public":true,"pinned":false,"body":"added comment","sensitive_data":null,"attachments":[],"mentioned_users":[],"mentioned_groups":[],"is_system":false,"is_autocomment":false,"timelog_date":null,"time_spent":null,"sync_statuses":[],"quoted_comment":null,"deleted":false,"is_ai_generated":false,"ai_agent_links":[]}

Updating the ticket (status, priority)

Endpoint: /api/tickets/{ID}/

Here, instead of ID, you need to insert the ID of the request in Swarmica, obtained when creating the request (Scenario 1)

Method: PATCH

Payload:

{
  "priority": "high",
  "status": "PENDING"
}

Example response:

{"id":56,"subject":"test API ticket 11111","ext_id":1,"requester":"j9m7sRnuAHFcWD9Q","assignee":null,"group":null,"status":"PENDING","until":null,"priority":"high","replies":4,"reopens":0,"created_at":"2026-08-20T08:10:00.432419Z","resolved_at":null,"updated_at":"2026-08-20T10:13:11.495034Z","is_fcr":false,"satisfaction_score":"UNOFFERED","custom_fields":[{"uid":"1KZHEyoEPQhaD0Ii","name":{"en":"Can grant access to environment","ru":"Могу дать доступ, если надо"},"mandatory_for":[],"value":null},{"uid":"ouVl3K0SUvirO-LR","name":{"en":"link","ru":"ссылка"},"mandatory_for":[],"value":null},{"uid":"UJB6rUrOw