API docs by Redocly

Amiko Dialogue Engine API (2025.4.0)

Download OpenAPI specification:Download

Operations exposed by the amiko Dialogue Engine for the Issuer Bank to integrate with. This API is to be used by your application frontend (portal or app), however for security reasons it is to be integrated with your application backend. This means your application backend acts as a (reverse)proxy between your frontend and the amiko Edge Connector.

Conversation

Returns one conversation for a given conversationId

The language is controlled via the language query parameter. If the language parameter is not provided, the engine will default to EN (english). Important: The cardId or cardholderId is NOT to be provided by the frontend (portal or app) but to be injected by the application backend as a request parameter. Your backend or integration layer (e.g. API Gateway) is to extract this information from an authenticated session. At least one of the two parameters needs to be present and only one should be present. If both are provided then the cardholderId will be used.

path Parameters
conversationId
required
string
query Parameters
language
string

Available values : EN, DE, FR, IT

cardId
string
cardholderId
string
formatting
boolean
salutation
boolean
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "conversationId": "string",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "caseId": "1234",
  • "caseType": "fraud",
  • "conversationStatus": "additional_response_required",
  • "hasUnreadMessages": true,
  • "associatedARNs": [
    ],
  • "firstUnreadMessageId": "30747951-2043-40dc-ac70-4613541f7d9d",
  • "dialogueCount": 0,
  • "dialogues": [
    ],
  • "lastUpdated": 1670935380000,
  • "initiatedBy": "agent",
  • "initiatedByDialogueType": "collect_affidavit",
  • "availableLanguages": [
    ],
  • "availableFollowupDialogues": [
    ],
  • "cardholderClaimOutcome": "cardholder_recognized_resolved",
  • "issuerId": "123456789"
}

Post an answer to a message with a pending response.

If the last message in a dialogue (meaning the messages with highest sequenceNr) is of a type that can be answered this endpoint is used to post the response. If the last message in a dialogue is of a different type, then there the dialogue is finished and no cardholder response is required/possible. The parameters on this endpoint are used to point to the conversation and the dialogue. The messageId for the message that is being answered is to be provided on the body.

path Parameters
conversationId
required
string
dialogueId
required
string
query Parameters
language
string

Available values : EN, DE, FR, IT

cardId
string
cardholderId
string
formatting
boolean
salutation
boolean
header Parameters
tracing-id
string
Request Body schema: application/json
required
type
required
string
Default: "free_text_answer"
messageId
required
string

Unique identifier for a message

answer
required
string

Responses

Request samples

Content type
application/json
Example
{
  • "type": "free_text_answer",
  • "messageId": "30747951-2043-40dc-ac70-4613541f7d9d",
  • "answer": "string"
}

Response samples

Content type
application/json
{
  • "conversationId": "string",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "caseId": "1234",
  • "caseType": "fraud",
  • "conversationStatus": "additional_response_required",
  • "hasUnreadMessages": true,
  • "associatedARNs": [
    ],
  • "firstUnreadMessageId": "30747951-2043-40dc-ac70-4613541f7d9d",
  • "dialogueCount": 0,
  • "dialogues": [
    ],
  • "lastUpdated": 1670935380000,
  • "initiatedBy": "agent",
  • "initiatedByDialogueType": "collect_affidavit",
  • "availableLanguages": [
    ],
  • "availableFollowupDialogues": [
    ],
  • "cardholderClaimOutcome": "cardholder_recognized_resolved",
  • "issuerId": "123456789"
}

Undo last answer.

This endpoint can be used to undo last answer in a dialogue when it's possible. The parameters on this endpoint are used to point to the conversation and the dialogue. The messageId for the message that is being answered is to be provided on the body.

path Parameters
conversationId
required
string
dialogueId
required
string
query Parameters
language
string

Available values : EN, DE, FR, IT

cardId
string
cardholderId
string
formatting
boolean
salutation
boolean
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "conversationId": "string",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "caseId": "1234",
  • "caseType": "fraud",
  • "conversationStatus": "additional_response_required",
  • "hasUnreadMessages": true,
  • "associatedARNs": [
    ],
  • "firstUnreadMessageId": "30747951-2043-40dc-ac70-4613541f7d9d",
  • "dialogueCount": 0,
  • "dialogues": [
    ],
  • "lastUpdated": 1670935380000,
  • "initiatedBy": "agent",
  • "initiatedByDialogueType": "collect_affidavit",
  • "availableLanguages": [
    ],
  • "availableFollowupDialogues": [
    ],
  • "cardholderClaimOutcome": "cardholder_recognized_resolved",
  • "issuerId": "123456789"
}

Patch a message to mark it as read.

Marks the specified message and all messages with a lower sequenceNr as read.

path Parameters
conversationId
required
string
dialogueId
required
string
messageId
required
string
query Parameters
cardId
string
cardholderId
string
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "tracingId": "5f27b818-027a-4008-b410-de01e1dd3a93",
  • "error": {
    }
}

Retrieve Conversation List

Returns the list of existing conversations for a given card or cardholder

Important: The cardId or cardholderId is NOT to be provided by the frontend (portal or app) but to be injected by the application backend as a request parameter. Your backend or integration layer (e.g. API Gateway) is to extract this information from an authenticated session. At least one of the two parameters needs to be present and only one should be present. If both are provided then the cardholderId will be used.

query Parameters
cardId
string
cardholderId
string
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "conversations": [
    ]
}

Document Handling

Download a document

Used to download a document using a documentId

path Parameters
conversationId
required
string
dialogueId
required
string
documentId
required
string
query Parameters
cardId
string
cardholderId
string
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "tracingId": "5f27b818-027a-4008-b410-de01e1dd3a93",
  • "error": {
    }
}

Upload a document

Used to upload a document in order to receive a documentId that can be used to answer a message of type upload_document. Only documents with certain mimeTypes are supported.

path Parameters
conversationId
required
string
dialogueId
required
string
query Parameters
cardId
string
cardholderId
string
header Parameters
tracing-id
string
Request Body schema: multipart/form-data
required
mimeType
required
string
document
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "documentId": "71633cc0-e45c-4662-a45f-4c5fa44c096a",
  • "documentType": "application/pdf"
}

Dialogue

Creates a cardholder-initiated Dialogue

The language is controlled via the language query parameter. If the language parameter is not provided, the engine will default to EN (english). Important: The cardId and cardholderId is NOT to be provided by the frontend (portal or app) but to be injected by the application backend as a request parameter. Your backend or integration layer (e.g. API Gateway) is to extract this information from an authenticated session.

query Parameters
language
string

Available values : EN, DE, FR, IT

cardId
required
string
cardholderId
required
string
formatting
boolean
salutation
boolean
issuerId
string
header Parameters
tracing-id
string
Request Body schema: application/json
required
dialogueType
required
string
Default: "development_test"
required
Array of objects (tech.rivero.edgeconnector.domain.dialogueengine.CreateCardholderInitiatedDialogueRequest.DevelopmentTest.DevelopmentTestTransactionDetails)

Responses

Request samples

Content type
application/json
Example
{
  • "dialogueType": "development_test",
  • "transactionDetails": [
    ]
}

Response samples

Content type
application/json
{
  • "conversationId": "string",
  • "cardholderId": "2bd52a45-129d-4723-9143-e1c5b5ed34e7",
  • "cardId": "b8ba25f3-c945-4ed0-9d4d-e3153a0dd048",
  • "caseId": "1234",
  • "caseType": "fraud",
  • "conversationStatus": "additional_response_required",
  • "hasUnreadMessages": true,
  • "associatedARNs": [
    ],
  • "firstUnreadMessageId": "30747951-2043-40dc-ac70-4613541f7d9d",
  • "dialogueCount": 0,
  • "dialogues": [
    ],
  • "lastUpdated": 1670935380000,
  • "initiatedBy": "agent",
  • "initiatedByDialogueType": "collect_affidavit",
  • "availableLanguages": [
    ],
  • "availableFollowupDialogues": [
    ],
  • "cardholderClaimOutcome": "cardholder_recognized_resolved",
  • "issuerId": "123456789"
}

Rich Transaction Data

Fetch image data for a merchant or industry logo

Used to fetch image data for a logo ID provided in the rich transaction data message

path Parameters
logoId
required
integer <int64>
header Parameters
tracing-id
string

Responses

Response samples

Content type
application/json
{
  • "tracingId": "5f27b818-027a-4008-b410-de01e1dd3a93",
  • "error": {
    }
}

Utility

Returns the health status for this API

The specification is based on the IETF draft linked below. Its content consists of a single mandatory root field (“status”) and several optional fields. Health Check Response Format for HTTP APIs: https://inadarei.github.io/rfc-healthcheck/

Responses

Response samples

Content type
application/json
{
  • "status": "pass",
  • "version": "string",
  • "output": "string",
  • "checks": {
    }
}