Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel4

Introduction

With our API it is possible to create PayLinks, e-Mandates and import records for our scripts. To use the PayLink and e-Mandate service, additional configuration and setup are required. Please contact our customer support if you would like to use additional services.

Please also read our Import and Result Data formats document.

GraphQL

Our API is written in GraphQL. On How To GraphQL you can read the fundamentals. Creating PayLinks should be as easy as using a REST API. We have added some examples of how to use our API with a GraphQL Client.

To explore our API and its documentation you could use the Altair GraphQL Client. This client has the option to set the required authentication header. Watch this demo video to view how to use the built-in documentation browser. 


Example collection for Altair

To explore our API and view all available fields, import the following collection to the Altair Client and update the header with your API key.

View file
namealphacomm_collectmaxx_example.agc

API endpoint

Code Block
https://reminders.alphacommapi.com/v1

We use load balancers so a IP change is possible at any time.

Test endpoint

Contact us for the test endpoint and credentials.

API Keys

You will need an access key to connect to our API. Your keys can be managed through our portal. At the portal go to "Account → API keys". You must be a portal manager for your company to access this page.

Key usage

For each request set the "X-AUTH-TOKEN" HTTP header with your key.

Key IP restriction

It is possible to allow keys to only work from certain IP addresses.

Code Block
127.1.1.1
192.1.0.0/32


Code example

We created one request example in PHP to get you started.

APIs

Through our API we provide multiple services. The requirements for fields are defined in the API itself. Use a GraphQL client to view the documentation. In this document, we will give you some examples to get started.

All the dates fields in our responses are formatted in RFC 3339, 'Y-m-d\TH:i:sP'.

Import

The import API is an alternative for our batch SFTP (CSV) import. Through this endpoint, you are able to import records. The records are batched and visible in the portal on the import page.

Note

When sending records to our API, we still starting import the records according to your account’s Import schedule. These import windows are visible at your upload page.

Info

The reminder results are reported at the end of the day in one or multiple result files, grouped by script. For more information see our Import and Result Data formats document.

Required fields

The scripts that are set up in our portal may be set up for voice messages, text messages or emails, that optionally contain a PayLink or e-Mandate. Each script has its own set of required fields. 

When a new script is set up we will provide a list of required fields. You can also use our matrix of required fields for medium and services.

Status codes

More information about status codes, which are used at the portal and API.

Batch statuses

Name

Description

empty

No records added to this batch yet.

queued

Records are waiting to be processed.

running

Records are being processed.

done

Records have finished processing.

error

Something went wrong.

Record statuses

Name

Description

notLoaded

Records that could not be read.

loaded

Records that have been read.

rejected

Records that could not be converted into a job.

accepted

Records that could be converted into a job.

enriching

Records that are currently enriching.

created

Records that have created a new job.

updated

Records that have updated an existing job.

dropped

Records that could not be saved to the database.

Input options

Through the 'addRecords' mutation you are able to add records.

Argument

Description

When to use

rows [RowInput!]

An endpoint that has a preset of fields.

This is the preferred way to deliver your records and usable in most cases.
Use this option for small batches or loose records.

file [FileInput!]

Base64 encoded file.

For example: csv, xml, xlsx, xls, ods.

For large batch import, 1000 or more.
Or when your script requires fields that are not available at the RowInput.

If you have questions please contact us.

Examples

When we set up a new script we will inform you about the required fields.

Row Input

This is an example of a mail with PayLink record using the RowInput.

Status
colourGreen
titlePOST
Query body
Code Block
mutation addRecords (
  $file: FileInput,
  $rows: [RowInput!]
) {
  import {
    addRecords(file: $file, rows: $rows) {
      name
      action
      status
      records {
        scriptId
        status
        reference
        messages {
          context
          message
          level
        }
      }
    }
  }
}
Variables
Code Block
{
    "rows": [
      {
        "reference": "f0e7a0c3",
        "script": "1001",
        "personFamilyName": "Alphacomm",
        "toMailAddress": "reminders@alphacomm.nl",
        "toPhoneNumbers" => [
         "+31612345678",
        ],
        "invoiceDescription": "Example payment",
        "invoiceDate": "2019-04-04",
        "invoiceDueDate": "2019-07-30",
        "invoiceReference": "40824524",
        "invoiceCurrency": "EUR",
        "invoiceAmount": "56445",
        "invoiceNumber": "249075245",
        "personBirthDay": "2000-01-01"
      }
    ]
}
Response
Status
title200

We only return the records that were send during the request. This makes it easier to validate if added records are accepted, using the record’s reference.

Code Block
{
  "data": {
    "import": {
      "addRecords": {
        "name": "20190403-965",
        "action": "IMPORT",
        "status": "done",
        "records": [
          {
            "reference": "f0e7a0c3",
            "scriptId": "1001",
            "status": "accepted",
            "messages": []
          }
        ]
      }
    }
  }
}


File Input

This is an example with FileInput. Your file should be sent as a Base64 encoded string. An imported file will always respond with a status queued. The slight delay is deliberate because we need time to process all records. It is possible to send a second request to get the status of the batch.

Status
colourGreen
titlePOST
Query body
Code Block
mutation addFile (
  $file: FileInput,
  $rows: [RowInput!]
) {
  import {
    addRecords(file: $file, rows: $rows) {
      name
      action
      status
    }
  }
}
Variables
Code Block
{
  "file": {
   "extension": "csv",
   "contents": "<<BASE64 ENCODED STRING>>"
  }
}
Response
Status
title200

When a file is imported we will always respond with a status queued. Bacause we need some time to process the file.

Code Block
{
  "data": {
    "import": {
      "addRecords": {
        "name": "20190404-579",
        "action": "IMPORT",
        "status": "queued",
        "records": []
      }
    }
  }
}


Search batches

This is an example of searching for a batch by name.

Status
colourGreen
titlePOST
Query body
Code Block
query ImportSearch(
  $filters: BatchFiltersInput
) {
  import {
    batches(
      filters: $filters
    ) {
      items {
        name
        action
        status
      }
      pagination {
        offset
        limit
        total
      }
    }
  }
}
Variables
Code Block
{
  "filters": {
    "name": {
      "equalTo": "Test"
    }
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "import": {
      "batches": {
        "items": [
          {
            "name": "Test",
            "action": "VALIDATE",
            "status": "empty"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 20,
          "total": 1
        }
      }
    }
  }
}


To use this service we need to configure your iDEAL bank credentials and set up a landing page. Please contact us if you would like to use this service.

Status codes

Name

Description

ready

PayLink is created in our service.

started

Transaction has been started.

partially_paid

A part of the original PayLink amount is paid.

paid

The complete PayLink amount is paid.

cancelled

The last transaction of the PayLink has been cancelled.

failed

The last transaction of the PayLink has failed.

Examples

To make your start easier we have added some examples of common actions.

Keep in mind to use the POST method on all your request.

When using GraphQL you have the ability to define what fields you get in the response. For this example, we only want the id of the created PayLink and the URLs.

Status
colourGreen
titlePOST
Query body
Code Block
mutation createPayLink($payLink: PayLinkInput!){
  payLink {
    create (payLink: $payLink) {
      attributes { id value }
      id
      shortUrl
      longUrl
    }
  }
}
Variables

This is the minimal information we need to create a PayLink.

Us the field visibleUntil to set the date when payment should not be possible anymore.

By default, the PayLink expires 90 days after the date of creation.

Code Block
{
   "payLink": {
    "attributes": [
      {"id": "source", "value": "whatsapp"}
    ],
    "personName": "Alphacomm",
    "invoiceAmount": "15497",
    "invoiceCurrency": "EUR",
    "invoiceDescription": "Example",
    "invoiceReference": "103482",
    "invoiceDate": "2019-02-12T10:00:00+00:00"
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "create": {
        "attributes": [
          {
            "id": "customer_source",
            "value": "whatsapp"
          },
          {
            "id": "origin",
            "value": "api"
          }
        ],
        "id": "a62c3726-d3b2-4b8c-8e4c-48ee0fd9451c",
        "shortUrl": "https://ibanaccept.com/u8t1nbw",
        "longUrl": "https://alphacomm.ibanaccept.com/pay/a62c3726-d3b2-4b8c-8e4c-48ee0fd9451c"
      }
    }
  }
}


Simple PayLink search

A basic search on all PayLinks.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query {
  payLink {
    payLinks {
      items {
        status
        id
      }
      pagination {
        offset
        limit
        total
      }
    }
  }
}
Variables

No variables are needed for this query.

Code Block
{}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "payLinks": {
        "items": [
          {
            "status": "paid",
            "id": "a6e8b63c-927f-476b-8d47-d323e20e1a4f"
          },
          {
            "status": "cancelled",
            "id": "348bd90d-da76-4211-93c3-601cbb15f33a"
          },
          {
            "status": "ready",
            "id": "389f0187-6b5d-4896-8d78-e56a6bb1a156"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 20,
          "total": 3
        }
      }
    }
  }
}

An example of how to get the status of a single PayLink.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query PayLinks(
  $filters: PayLinkFiltersInput
) {
  payLink {
    payLinks (
      filters: $filters
    ) {
        items {
          id
          personName
          personGender
          status
          amountPaid
          createdOn
          updatedOn
        }
      }
    }
}
Variables
Code Block
{
  "filters": {
    "id": {
      "equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70"
    }
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "payLinks": {
        "items": [
          {
            "id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
            "personName": "Demo",
            "personGender": "U",
            "status": "paid",
            "amountPaid": 0,
            "createdOn": "2019-02-05T09:57:14+00:00",
            "updatedOn": "2019-02-05T09:57:14+00:00"
          }
        ]
      }
    }
  }
}

Search PayLink with record identifer

PayLinks can not only be created through our API but also though the import to our scripts. In this last case the PayLink is delivered by us via email or SMS.

During a record import you are required to define the ‘idenfification_identifier' or also called 'reference’. In case you want to know what the current status of the PayLink is your are able to search our PayLink service with this reference.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query PublicApiPayLinks(
  $filters: PayLinkFiltersInput
  $order: PayLinkOrderInput
  $offset: Int
  $limit: Int
) {
  payLink {
    payLinks (
      filters: $filters
      order: $order
      offset: $offset
      limit: $limit
    ) {
        items {
          attributes {
            id
            value
          }
          id
          personName
          personGender
          status
        }
      }
    }
}
Variables
Code Block
{
  "filters": {
    "attributes": [
      {
      	"id": "reference",
      	"equalTo": "20220216-6"
    	}
    ]
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "payLinks": {
        "items": [
          {
            "attributes": [
              {
                "id": "origin",
                "value": "sms"
              },
              {
                "id": "script",
                "value": "1003"
              },
              {
                "id": "reference",
                "value": "20220216-6"
              }
            ],
            "id": "42c949b9-5945-4273-912d-00f5563df1fd",
            "personName": "Alphacomm",
            "personGender": "M",
            "status": "ready"
          }
        ]
      }
    }
  }
}

Advanced PayLink search

An example of how to find all PayLinks with the status paid created on 08-02-2019.

You have the option to set filters, order, offset and limit. All the options are defined in the API docs.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query PayLinks(
  $filters: PayLinkFiltersInput
  $order: PayLinkOrderInput
  $offset: Int
  $limit: Int
) {
  payLink {
    payLinks (
      filters: $filters
      order: $order
      offset: $offset
      limit: $limit
    ) {
        items {
          id
          personName
          personGender
          status
          amountPaid
          createdOn
          updatedOn
        }
        pagination {
          offset
          limit
          total
        }
      }
    }
}
Variables
Code Block
{
  "filters": {
    "status": {
      "equalTo": "paid"
    },
    "createdOn": {
      "greaterThan": "2019-02-08T00:00:00+00:00",
      "lesserThan": "2019-02-09T00:00:00+00:00"
    }
  },
  "order": {
    "createdOn": "DESCENDING"
  },
  "offset": 0,
  "limit": 20
}
Response
Status
title200
Code Block
{
  "data": {
    "payLink": {
      "payLinks": {
        "items": [
          {
            "id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
            "personName": "Demo",
            "personGender": "U",
            "status": "paid",
            "amountPaid": 0,
            "createdOn": "2019-02-05T09:57:14+00:00",
            "updatedOn": "2019-02-05T09:57:14+00:00"
          },
          {
            "id": "96f3cf79-98ab-43d1-80ca-fa5c9fccab23",
            "personName": "Test Person",
            "personGender": "U",
            "status": "paid",
            "amountPaid": 0,
            "createdOn": "2019-02-01T14:49:35+00:00",
            "updatedOn": "2019-02-01T14:49:36+00:00"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 0,
          "total": 2
        }
      }
    }
  }
}


E-Mandate

To use this service we need to configure your e-Mandate bank credentials and setup a landing page. Please contact us if you would like to use this service.

Status codes

Name

Description

new

Mandate is created on our service.

pending

Waiting for second authorization.

success

Mandate is given.

Examples

To make your start easier we have added some examples of common actions.

Keep in mind to use the POST method on all your request.

Create Mandate

When using GraphQL you have the ability to define what fields you get in the response. For this example, we only want the id, reference, URLs and type.

Status
colourGreen
titlePOST
Query body
Code Block
mutation createMandate($mandate: MandateInput!){
  mandate {
    create (mandate: $mandate) {
      id
      reference
      shortUrl
      longUrl
      type
    }
  }
}
Variables

Example values.

Code Block
{
  "mandate": {
    "personName": "Alphacomm",
    "reference": "AC-HUUR"
    "type": "RCUR",
    "reason": "huur",     
    "debtorReference": "20190301"
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "mandate": {
      "create": {
        "id": "4442ddf6-7371-4e6a-8939-087f8fd3b17c",
        "reference": "AC-HUUR",
        "shortUrl": "https://betaalmachtiging.nl/akps797",
        "longUrl": "https://alphacomm.betaalmachtiging.nl/pay/94e592f0-9f21-4404-bdfe-a6e51c6bf547",
        "type": "RCUR"
      }
    }
  }
}


Simple Mandate search

A basic search query for all Mandates.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query {
  mandate {
    mandates {
      items {
        status
        id
      }
    }
  }
}
Variables

No variables are needed for this query.

Code Block
{}
Response
Status
title200
Code Block
{
  "data": {
    "mandate": {
      "mandates": {
        "items": [
          {
            "status": "new",
            "id": "a6e8b63c-927f-476b-8d47-d323e20e1a4f"
          },
          {
            "status": "pending",
            "id": "348bd90d-da76-4211-93c3-601cbb15f33a"
          },
          {
            "status": "success",
            "id": "389f0187-6b5d-4896-8d78-e56a6bb1a156"
          }
        ]
      }
    }
  }
}

Find Single Mandate

An example of how to get the status of a single Mandate.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query Mandates(
  $filters: MandateFiltersInput
) {
  mandate {
    mandates (
      filters: $filters
    ) {
        items {
          id
          personName
          status
          createdOn
          updatedOn
        }
      }
    }
}
Variables
Code Block
{
  "filters": {
    "id": {
      "equalTo": "5be41c4f-9fe6-403d-980b-5edc0139ee70"
    }
  }
}
Response
Status
title200
Code Block
{
  "data": {
    "mandate": {
      "mandates": {
        "items": [
          {
            "id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
            "personName": "Demo",
            "status": "success",
            "createdOn": "2019-02-05T09:57:14+00:00",
            "updatedOn": "2019-02-05T09:57:14+00:00"
          }
        ]
      }
    }
  }
}


Advanced Mandate search

An example of how to find all e-Mandates with the status success, created on 08-02-2019.

You have the option to set filters, order, offset and limit. All the options are defined in the API docs.

Status
colourGreen
titlePOST
Query body
Code Block
languagephp
query Mandates(
  $filters: MandateFiltersInput
  $order: MandateOrderInput
  $offset: Int
  $limit: Int
) {
  mandate {
    mandates (
      filters: $filters
      order: $order
      offset: $offset
      limit: $limit
    ) {
        items {
          id
          personName
          status
          createdOn
          updatedOn
        }
        pagination {
          offset
          limit
          total
        }
      }
    }
}
Variables
Code Block
{
  "filters": {
    "status": {
      "equalTo": "success"
    },
    "createdOn": {
      "greaterThan": "2019-02-08T00:00:00+00:00",
      "lesserThan": "2019-02-09T00:00:00+00:00"
    }
  },
  "order": {
    "createdOn": "DESCENDING"
  },
  "offset": 0,
  "limit": 20
}
Response
Status
title200
Code Block
{
  "data": {
    "mandate": {
      "mandates": {
        "items": [
          {
            "id": "5be41c4f-9fe6-403d-980b-5edc0139ee70",
            "personName": "Demo",
            "status": "success",
            "createdOn": "2019-02-05T09:57:14+00:00",
            "updatedOn": "2019-02-05T09:57:14+00:00"
          },
          {
            "id": "96f3cf79-98ab-43d1-80ca-fa5c9fccab23",
            "personName": "Test Person",
            "status": "success",
            "createdOn": "2019-02-01T14:49:35+00:00",
            "updatedOn": "2019-02-01T14:49:36+00:00"
          }
        ],
        "pagination": {
          "offset": 0,
          "limit": 0,
          "total": 2
        }
      }
    }
  }
}



Voice

To use this service we need to configure a voice script. Please contact us if you would like to use this service.

Examples

To make your start easier we have added some examples of common actions.

Stop Calling

Use this action to remove any leftover scheduled voice calls, related to the specified scriptId and reference.

Status
colourGreen
titlePOST
Query body
Code Block
mutation stopCalling(
  $scriptId: Int!
  $reference: String!
){
  voice {
    stopCalling (
      scriptId: $scriptId
      reference: $reference
    )
  }
}
Variables
Code Block
{
  "scriptId": 18301,
  "reference": "your_identifier"
}
Response
Status
title200
Code Block
{
  "data": {
    "voice": {
      "stopCalling": "done"
    }
  }
}

Webhook events

Note

We are working on adding more events and improving the information in the payload. So the content of the data might change.

Voice

Call completed

Legacy format

The voice service supports the use of webhook messages. When a voice call has been completed the result will be reported to your webhook URL. We can authenticate to your webhook with basic access authentication.

Contact us to configure your webhook URL.

Format

The webhook request is a standard HTTP POST request with a JSON body, which is formatted as follows.

Field

Format

id
string

UUID, identifying the call uniquely

attributes
array

Contains the 'reference' used at import (identification_identifier).

direction
string

Call direction

ENUM DIRECTION

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the call.

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the Call Request.

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

serviceId
string

voice

reference
string

Identifier used during import, also know as identification_identifier

event
string

Code Block
VoiceCallCompleted

data
array

See Data table below.

Data

direction
string

Call direction

ENUM DIRECTION

Code Block
  outbound
  inbound

status
string

The call status

ENUM STATUS

Code Block
  ringing
  active
  finished
  no answer
  busy
  rejected
  invalid number
  failed

localNumber
string

E164

remoteNumber
string

E164

events
array

Array of events during the call,
contains the following fields

Code Block
languagejson
nodeId: string, node identifier
nodeType: string, ENUM NODETYPE
order: int, event order
type: string, ENUM EVENTTYPE
data: array, data that is specific to the node type and event type
time: string, RFC3339

Empty when call is not answered.

Code Block
NODETYPE:
  AddResult
  CheckCallAttempt
  CheckCounter
  CheckGenderBirthday
  CheckVariable
  DTMF
  DTMFString
  Forward
  Hangup
  IsCallOutbound
  IsRemoteMobile
  IsRemoteVoiceMail
  IsTimeInInterval
  Sound
  WaitForSilence

EVENTTYPE:
  NodeStart
  NodeUpdate
  NodeResult

createdOn
string

RFC3339
2019-10-12T07:20:50.52Z

updatedOn
string

RFC3339
2019-10-12T07:20:50.52Z

answeredOn
string

not set if the call has not been answered.

RFC3339
2019-10-12T07:20:50.52Z

How to determine a call has reached the success point

To determine a call was successful a defined point in the voice message should be reached.

This is always an AddResult type node with a data result value success-ok

Code Block... "events": [ { "nodeId": "success", "nodeType": "AddResult",

Example

Expand
titleCall completed, answered
Code Block
{
  "datetime": "2022-09-08T14:22:52+00:00",
  "id": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "serviceId": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "service": "voice",
  "reference": "20231208-1547471",
  "event": "VoiceCallCompleted",
  "data": {
    "
order
direction": 
16
"outbound",
    
"
type
status": "
NodeResult
finished",
    "localNumber": "3225882397",
  
"data":
 
{
 
"
result
remoteNumber": "
success-ok
316123456789",
    
},
"answeredOn": "2022-09-08T14:23:10+00:00",
    "
time
events": 
"2020-05-06T08:43:11+00:00"
[
      {
 
}
     
]
 
...
Info

Use the NodeResult type with the data['result'] value when evaluating the events. The NodeId’s are more likely to change when altering voice script flows.

Example message for an outbound call

Code Block
languagejson
{
 
"
id
nodeId": "
e7813601-21ae-465c-bd97-96367bebd0ca
vm_beep",
"attributes": { "origin": "annabel", "customer
        "nodeType": "
6500
Sound",
"script

        "order": 
"6512", "job
1,
        "type": "
eb44f88bd968749a620765a382ef3c75c20a657c37499392d59958c5dd944652-06512
NodeStart",
"reference": "API reference / identification_identifier" }, "direction": "outbound", "status": "finished", "localNumber": "31513703800", "remoteNumber": "31640754459", "events": [{

        "data": [],
        "time": "2022-09-08T14:23:13+00:00"
      },
      {
        "nodeId": "vm_beep",

        "nodeType": "Sound",
        "order": 
1,
2,
        "type": "
NodeStart
NodeResult",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
42
23:
55
16+00:00"
      },
      {
        "nodeId": "vm_
beep
wait_for_silence",

        "nodeType": "
Sound
WaitForSilence",

        "order": 
2
3,
        "type": "
NodeResult
NodeStart",
        "data": [],
"time": "2020-05-06T08:42:59
        "time": "2022-09-08T14:23:17+00:00"
      },
      {
        "nodeId": "vm_wait_for_silence",

        "nodeType": "WaitForSilence",
        "order": 
3
4,
        "type": "
NodeStart
NodeResult",

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
42
23:
59
18+00:00"
 
     },
      {

        "nodeId": 
"vm_is_vm",
"name",
        "nodeType": "
IsRemoteVoiceMail
Sound",

        "order": 5,

        "type": "NodeStart",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
00
18+00:00"
      },
      {

        "nodeId": "
text10
name",

        "nodeType": "Sound",
        "order": 
7
6,

        "type": "
NodeStart
NodeResult",
"data":
 
[],
       "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
00
20+00:00"
      },
      {

        "nodeId": "
text10
invoice_reference",

        "nodeType": "Sound",
        "order": 
8
7,

        "type": "
NodeResult
NodeStart",

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
20+00:00"
      
},
 
{
     {
        "nodeId": "
filter
invoice_reference",
        "nodeType": "
CheckGenderBirthday
Sound",

        "order": 
9,
8,
        "type": "
NodeStart
NodeResult",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
22+00:00"
      },
      {

        "nodeId": "
filter
vmresult",
        "nodeType": "
CheckGenderBirthday
IsRemoteVoiceMail",

        "order": 
10
9,
        "type": "
NodeResult
NodeStart",

        "data": 
{ "gender": "M", "age": 2020, "outcome": "man" },
[],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
22+00:00"
      },
      {
        "nodeId": "
text11m
vmresult",

        "nodeType": "
Sound
IsRemoteVoiceMail",
        "order": 
11,
10,
        "type": "
NodeStart
NodeResult",
"data": [],
        "data": {
          "detected": "HUMAN",
          "outcome": "no"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
05
22+00:00"
     
 },
      {
        "nodeId": "
text11m
text2",
        "nodeType": "Sound",

        "order": 
12
11,
 
"type": "NodeResult",
       "type": "NodeStart",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
08
22+00:00"
      },
      {
        "nodeId": "
name
text2",
        "nodeType": "Sound",

        "order": 
13
12,
        "type": "
NodeStart
NodeResult",
        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
09
25+00:00"
}, {
      },
      {
        "nodeId": "
name
success",

        "nodeType": "
Sound
AddResult",
        "order": 
14
13,

        "type": "
NodeResult
NodeStart",

        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
10
25+00:00"
 
     },
      {
        "nodeId": "success",

        "nodeType": "AddResult",

        "order": 
15
14,
        "type": "
NodeStart
NodeResult",
"data": [],

        "data": {
          "result": "success-ok"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
25+00:00"
      
},
      {

        "nodeId": "
success
text3",
        "nodeType": "
AddResult
DTMF",

        "order": 
16
15,
 
"type": "NodeResult", "data": { "result": "success-ok" },
       "type": "NodeStart",
        "data": [],
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
25+00:00"
      },
      {
        "nodeId": "
collect_id
text3",
        "nodeType": "
Sound
DTMF",

        "order": 
17
16,
        "type": "
NodeStart
NodeResult",

        "data":
[],
 {
          "input": [
            "3"
          ],
          "outcome": "tone:3"
        },
        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
11
31+00:00"
      
},
      {

        "nodeId": "
collect
pre_send_
id
sms",

        "nodeType": "Sound",
        "order": 
18,
17,
        "type": "
NodeResult
NodeStart",

        "data": [],

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
16
32+00:00"
      },
      {

        "nodeId": "
text22
remote_hangup",

        "nodeType": "
Sound
RemoteHangup",

        "order": 
19
18,
        "type": "
NodeStart
RemoteHangup",

        "data": [],
"time": "2020-05-06T08:43:17+00:00" }, { "nodeId": "text22", "nodeType": "Sound", "order": 20, "type": "NodeResult", "data": [], "

        "time": "
2020
2022-
05
09-
06T08
08T14:
43
23:
23
33+00:00"
},
 
{
 
"nodeId":
 
"amount",
 
"nodeType":
 
"Sound", "order": 21, "type": "NodeStart", "data": [], "time": "2020-05-06T08:43:24+00:00" }, { "nodeId": "amount", "nodeType": "Sound", "order": 22, "type": "NodeResult", "data": [], "time": "2020-05-06T08:43:28+00:00" }, { "nodeId": "text30", "nodeType": "Sound", "order": 23, "type": "NodeStart", "data": [], "time": "2020-05-06T08:43:29+00:00" }, { "nodeId": "text30", "nodeType": "Sound", "order": 24, "type": "NodeResult", "data": [], "time": "2020-05-06T08:43:45+00:00" }, { "nodeId": "text31", "nodeType": "Sound", "order": 25, "type": "NodeStart", "data": [], "time": "2020-05-06T08:43:46+00:00" }, { "nodeId": "text31", "nodeType": "Sound", "order": 26, "type": "NodeResult", "data": [], "time": "2020-05-06T08:44:07+00:00" }, { "nodeId": "businesshours", "nodeType": "IsTimeInInterval", "order": 27, "type": "NodeStart", "data": [], "time": "2020-05-06T08:44:07+00:00" }, { "nodeId": "businesshours_forward_switch", "nodeType": "CheckVariable", "order": 29, "type": "NodeStart", "data": [], "time": "2020-05-06T08:44:07+00:00" }, { "nodeId": "text40", "nodeType": "DTMF", "order": 31, "type": "NodeStart", "data": [], "time": "2020-05-06T08:44:07+00:00" }, { "nodeId": "text40", "nodeType": "DTMF", "order": 32,
 }
    ]
  }
}

PayLink

Event

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the event uniquely

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the PayLink

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

serviceId
string

paylink

reference
string

Identifier used during import, also know as identification_identifier

Empty when created through our API.

event
string

Code Block
PayLinkVisited
PayLinkPaid

data
array

Code Block
{
"payment-method": "ideal",
"transaction-amount": 1344 # Amount in cents
}

Example Paid

Code Block
{
  "datetime": "2022-11-11T11:11:11.11Z",
  "id": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "reference": "",
  "serviceId": "adbc180b-a494-477f-958d-9f0b050a09c3",
  "service": "paylink",
  "event": "PayLinkPaid",
  "data": {
    "payment-method": "ideal",
    "transaction-amount": 114
  }
}

Voice webhook V1

Call completed Legacy format

The voice service supports the use of webhook messages. When a voice call has been completed the result will be reported to your webhook URL. We can authenticate to your webhook with basic access authentication.

Contact us to configure your webhook URL.

Format

The webhook request is a standard HTTP POST request with a JSON body, which is formatted as follows.

Field

Format

id
string

UUID, identifying the call uniquely

attributes
array

Contains the 'reference' used at import (identification_identifier).

direction
string

Call direction

ENUM DIRECTION

Code Block
  outbound
  inbound

status
string

The call status

ENUM STATUS

Code Block
  ringing
  active
  finished
  no answer
  busy
  rejected
  invalid number
  failed

localNumber
string

E164

remoteNumber
string

E164

events
array

Array of events during the call,
contains the following fields

Code Block
languagejson
nodeId: string, node identifier
nodeType: string, ENUM NODETYPE
order: int, event order
type: string, ENUM EVENTTYPE
data: array, data that is specific to the node type and event type
time: string, RFC3339

Empty when call is not answered.

Code Block
NODETYPE:
  AddResult
  CheckCallAttempt
  CheckCounter
  CheckGenderBirthday
  CheckVariable
  DTMF
  DTMFString
  Forward
  Hangup
  IsCallOutbound
  IsRemoteMobile
  IsRemoteVoiceMail
  IsTimeInInterval
  Sound
  WaitForSilence

EVENTTYPE:
  NodeStart
  NodeUpdate
  NodeResult

createdOn
string

RFC3339
2019-10-12T07:20:50.52Z

updatedOn
string

RFC3339
2019-10-12T07:20:50.52Z

answeredOn
string

not set if the call has not been answered.

RFC3339
2019-10-12T07:20:50.52Z

How to determine a call has reached the success point

To determine a call was successful a defined point in the voice message should be reached.

This is always an AddResult type node with a data result value success-ok

Code Block
...
	"events": [
      {
        "nodeId": "success",
        "nodeType": "AddResult",
        "order": 16,
        "type": "NodeResult",
		        "data": {
			"inputresult": [],
			"outcome": "timeout"
		},
		"success-ok"
        },
        "time": "2020-05-06T08:4443:2011+00:00"
	}, {
		"nodeId": "text43
      }
    ]
...
Info

Use the NodeResult type with the data['result'] value when evaluating the events. The NodeId’s are more likely to change when altering voice script flows.

Example message for an outbound call

Expand

serviceId
string

voice

reference
string

Identifier used during import, also know as identification_identifier

event
string

Code Block
VoiceCallCompleted

data
array

See Data table below.

Data

direction
string

Call direction

ENUM DIRECTION

Code Block
  outbound
  inbound

status
string

The call status

ENUM STATUS

Code Block
  ringing
  active
  finished
  no answer
  busy
  rejected
  invalid number
  failed

localNumber
string

E164

remoteNumber
string

E164

events
array

Array of events during the call,
contains the following fields

Code Block
languagejson
nodeId: string, node identifier
nodeType: string, ENUM NODETYPE
order: int, event order
type: string, ENUM EVENTTYPE
data: array, data that is specific to the node type and event type
time: string, RFC3339

Empty when call is not answered.

Code Block
NODETYPE:
  AddResult
  CheckCallAttempt
  CheckCounter
  CheckGenderBirthday
  CheckVariable
  DTMF
  DTMFString
  Forward
  Hangup
  IsCallOutbound
  IsRemoteMobile
  IsRemoteVoiceMail
  IsTimeInInterval
  Sound
  WaitForSilence

EVENTTYPE:
  NodeStart
  NodeUpdate
  NodeResult

answeredOn
string

not set if the call has not been answered.

RFC3339
2019-10-12T07:20:50.52Z

Example

Expand
titleCall completed, answered
Code Block
languagejson
{
	"id": "e7813601-21ae-465c-bd97-96367bebd0ca",
	
"
nodeType
attributes": 
"Sound",
{
		"
order
origin": 
33
"annabel",
		"
type
customer": "
NodeStart
6500",
		"
data
script": 
[]
"6512",
		"
time
job": "
2020-05-06T08:44:20+00:00" }, {
eb44f88bd968749a620765a382ef3c75c20a657c37499392d59958c5dd944652-06512",
		"
nodeId
reference": "
text43"
API reference / identification_identifier"
	},
	"
nodeType
direction": "
Sound
outbound",
	
"
order
status": 
34
"finished",
	
"
type
localNumber": "
NodeResult
31513703800",
	"
data
remoteNumber": 
[]
"31640754459",
	
"
time
events": 
"2020-05-06T08:44:32+00:00" },
[{
		"nodeId": "
text44
vm_beep",
		"nodeType": "Sound",
		"order": 
35
1,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:
44
42:
32
55+00:00"
	}, {
		"nodeId": "
text44
vm_beep",
		"nodeType": "Sound",
		"order": 
36
2,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:
44
42:
36
59+00:00"
	}, {
		"nodeId": "
text45
vm_wait_for_silence",
		"nodeType": "
DTMF
WaitForSilence",
		"order": 
37
3,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:
44
42:
37
59+00:00"
	}, {
		"nodeId": "
text45
vm_is_vm",
		"nodeType": "
DTMF
IsRemoteVoiceMail",
		"order": 
38
5,
		"type": "
NodeResult
NodeStart",
		"data
": {
"
input"
: [],
		
"
outcome": "timeout" }, "
time": "2020-05-06T08:
44
43:
49
00+00:00"
	}, {
		"nodeId": "
exit
text10",
		"nodeType": "
Hangup
Sound",
		"order": 
40
7,
		"type": "
NodeResult
NodeStart",
		"data": [],
		"time": "2020-05-06T08:
44
43:
49
00+00:00"
	}
]
, {
		"
createdOn
nodeId": "
2020-05-06T08:42:48+00:00", "updatedOn": "2020-05-06T08:44:49+00:00", "answeredOn
text10",
		"nodeType": "Sound",
		"order": 8,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:
42
43:
54
05+00:00"
}

Example message for an anonymous or not recognized an inbound call

It is possible some is calling from a phone number we cannot match to a record or they have blocked their phone number.

In this case, we cannot provide the attribute reference.

Code Block
{
    "id": "94d21117-2768-498c-a401-1b17e581e441",
    "attributes": {
      "origin": "annabel",
      "customer": "1000",
      "script": "1001"
    },
    "direction": "inbound",
    "status": "finished",
    "localNumber": "31513703800",
    "remoteNumber": "anonymous",
    "events": 
      ..........
    ],
    "createdOn": "2021-05-19T12:18:25+00:00",
    "updatedOn": "2021-05-19T12:18:41+00:00",
    "answeredOn": "2021-05-19T12:18:26+00:00"
}

Call completed

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the call.

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the Call Request.

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

Code Block
{
  "datetime": "2022-09-08T14:22:52+00:00",
  "id": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "serviceId": "f3e445ce-75ee-4c94-9d6d-370949664fd7",
  "service": "voice",
  "reference": "20231208-1547471",
  "event": "VoiceCallCompleted",
  "data": {
    "direction": "outbound",
    "status": "finished",
    "localNumber": "3225882397",
    "remoteNumber": "316123456789",
    "answeredOn": "2022-09-08T14:23:10+00:00",
    "events": [
      {
        "nodeId": "vm_beep",
        	}, {
		"nodeId": "filter",
		"nodeType": "CheckGenderBirthday",
		"order": 9,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:43:05+00:00"
	}, {
		"nodeId": "filter",
		"nodeType": "CheckGenderBirthday",
		"order": 10,
		"type": "NodeResult",
		"data": {
			"gender": "M",
			"age": 2020,
			"outcome": "man"
		},
		"time": "2020-05-06T08:43:05+00:00"
	}, {
		"nodeId": "text11m",
		"nodeType": "Sound",
		"order": 11,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:43:05+00:00"
	}, {
		"nodeId": "text11m",
		"nodeType": "Sound",
		"order": 12,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:43:08+00:00"
	}, {
		"nodeId": "name",
		"nodeType": "Sound",
		"order": 13,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:43:09+00:00"
	}, {
		"nodeId": "name",
		"nodeType": "Sound",
		"order": 14,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:43:10+00:00"
	}, {
		"nodeId": "success",
		"nodeType": "AddResult",
		"order": 15,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:43:11+00:00"
	}, {
		"nodeId": "success",
		"nodeType": "AddResult",
		"order": 16,
		"type": "NodeResult",
		"data": {
			"result": "success-ok"
		},
		"time": "2020-05-06T08:43:11+00:00"
	}, {
		"nodeId": "collect_id",
		"nodeType": "Sound",
		"order": 17,
		"type": "NodeStart",
		"data": [],
		"time": "2020-05-06T08:43:11+00:00"
	}, {
		"nodeId": "collect_id",
		"nodeType": "Sound",
		"order": 18,
		"type": "NodeResult",
		"data": [],
		"time": "2020-05-06T08:43:16+00:00"
	}, {
		"nodeId": "text22",
		"nodeType": "Sound",
        		"order": 119,
        		"type": "NodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2343:1317+00:00"
      	},
      {
        		"nodeId": "vm_beeptext22",
        		"nodeType": "Sound",
        		"order": 220,
        		"type": "NodeResult",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:43:23:16+00:00"
      	},       {
        		"nodeId": "vm_wait_for_silenceamount",
        		"nodeType": "WaitForSilence",
        ": "Sound",
		"order": 321,
        		"type": "NodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2343:1724+00:00"
      	},
      {
        		"nodeId": "vm_wait_for_silenceamount",
        		"nodeType": "WaitForSilenceSound",
        		"order": 422,
        		"type": "NodeResult",
        		"data": [],
         [],
		"time": "20222020-0905-08T1406T08:2343:1828+00:00"
      	},
      {
        		"nodeId": "nametext30",
        		"nodeType": "Sound",
        		"order": 523,
        		"type": "NodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2343:1829+00:00"
      	},       {
        		"nodeId": "nametext30",
        
		"nodeType": "Sound",
        		"order": 624,
        		"type": "NodeResult",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2343:2045+00:00"
      	},
      {
        		"nodeId": "invoice_referencetext31",
        		"nodeType": "Sound",
        		"order": 725,
        		"type": "NodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2343:2046+00:00"
      	},
      {
        		"nodeId": "invoice_referencetext31",
        		"nodeType": "Sound",
        		"order": 826,
        		"type": "NodeResult",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2344:2207+00:00"
      	},       {
        		"nodeId": "vmresultbusinesshours",
        		"nodeType": "IsRemoteVoiceMailIsTimeInInterval",
        		"order": 927,
        		"type": "NodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2344:2207+00:00"
      	},       {
        		"nodeId": "vmresultbusinesshours_forward_switch",
		"nodeType": "CheckVariable",
		"order": 29,
		"type": "NodeStart",
		"data": [],
		"nodeTypetime": "IsRemoteVoiceMail"2020-05-06T08:44:07+00:00"
	},         "order{
		"nodeId": 10"text40",
        "type		"nodeType": "NodeResultDTMF",
        "data		"order": {
          "detected31,
		"type": "HUMANNodeStart",
          "outcome": "no"
        },
        		"data": [],
		"time": "20222020-0905-08T1406T08:2344:2207+00:00"
      	},
      {
        
		"nodeId": "text2text40",
        		"nodeType": "SoundDTMF",
        		"order": 1132,
        		"type": "NodeStartNodeResult",
		"data":        "data{
			"input": [],
			"outcome": "timeout"
      		},
		"time": "20222020-0905-08T1406T08:2344:2220+00:00"
      	},
      {
        		"nodeId": "text2text43",
        		"nodeType": "Sound",
        ": "Sound",
		"order": 1233,
        		"type": "NodeResultNodeStart",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2344:2520+00:00"
      	},       {
        		"nodeId": "successtext43",
        		"nodeType": "AddResultSound",
        		"order": 1334,
        		"type": "NodeStartNodeResult",
        "data": [],
        		"data": [],
		"time": "20222020-0905-08T1406T08:2344:2532+00:00"
      	},       {
        		"nodeId": "successtext44",
        		"nodeType": "AddResultSound",
        		"order": 1435,
        		"type": "NodeResultNodeStart",
        		"data": {
          "result": "success-ok"
        },
        [],
		"time": "20222020-0905-08T1406T08:2344:2532+00:00"
      	},
      {
        		"nodeId": "text3text44",
        		"nodeType": "DTMFSound",
        		"order": 1536,
        		"type": "NodeStartNodeResult",
        		"data": [],
        		"time": "20222020-0905-08T1406T08:2344:2536+00:00"
      	},       {
        		"nodeId": "text3",
         "text45",
		"nodeType": "DTMF",
        		"order": 1637,
        		"type": "NodeResultNodeStart",
        "data": {
          "input": [
            "3"
          ],
          "outcome": "tone:3"
        },
        "		"data": [],
		"time": "20222020-0905-08T1406T08:2344:3137+00:00"
      	},       {
        		"nodeId": "pre_send_smstext45",
        		"nodeType": "SoundDTMF",
        		"order": 1738,
        		"type": "NodeStartNodeResult",
		"data":        "data{
			"input": [],
			"outcome": "timeout"
      		},
		"time": "20222020-0905-08T1406T08:2344:3249+00:00"
      },
      {
        "
	}, {
		"nodeId": "remote_hangupexit",
        		"nodeType": "RemoteHangupHangup",
        		"order": 1840,
        		"type": "RemoteHangupNodeResult",
        		"data": [],
		"time": "2020-05-06T08:44:49+00:00"
	}],
	"createdOn": "2020-05-06T08:42:48+00:00",
	"updatedOn":   "time"2020-05-06T08:44:49+00:00",
	"answeredOn": "20222020-0905-08T1406T08:2342:3354+00:00"
      }
  
 ]
  }
}

PayLink

Event

Field

Format

datetime
string

When the event occurred

RFC3339
2023-10-12T07:20:50.52Z

id
string

Identifying the event uniquely

UUID

d670a4af-8562-4d5f-ae30-5cc36acf82ee

serviceId
string

Identifier of the PayLink

UUID

a2654d8a-3f8d-402e-a03b-980953802a09

serviceId
string

paylink

reference
string

Identifier used during import, also know as identification_identifier

Empty when created through our API.

event
string

Code Block
PayLinkVisited
PayLinkPaid

data
array

Code Block
{
"payment-method": "ideal",
"transaction-amount": 1344 # Amount in cents
}

Example Paid

Code Block
{ "datetime": "2022-11-11T11:11:11.11Z", "id": "f3e445ce-75ee-4c94-9d6d-370949664fd7", "reference": "", "serviceId": "adbc180b-a494-477f-958d-9f0b050a09c3", "service": "paylink", "event": "PayLinkPaid", "data": { "payment-method": "ideal
}

Example message for an anonymous or not recognized an inbound call

It is possible some is calling from a phone number we cannot match to a record or they have blocked their phone number.

In this case, we cannot provide the attribute reference.

Code Block
{
    "id": "94d21117-2768-498c-a401-1b17e581e441",
    "attributes": {
      "origin": "annabel",
      "customer": "1000",
      "script": "1001"
    },
    "direction": "inbound",
    "status": "finished",
    "localNumber": "31513703800",
    "remoteNumber": "anonymous",
    "events": 
      ..........
    ],
    "createdOn": "2021-05-19T12:18:25+00:00",
    "updatedOn": "2021-05-19T12:18:41+00:00",
    "transaction-amountansweredOn": 114
  }
}
"2021-05-19T12:18:26+00:00"
}