Adversus

This plugin allows for API integration with Adversus.

Installation

To install this module:

composer require qore/adversus

Getting started

After you enable this plugin in the interface, you will be required to fill in the Username and Password.

You can find this information here.

After saving, you should be ready to make API calls.

info

Adversus' API Documentation can be found here

Usage

You can start making request to Adversus with the following client:

$client = new AdversusClient();

The client will automatically use the credentials stored inside the Qore settings, however you can override this:

$client = new AdversusClient();
$client->setCredentials('username', 'password');

Most resources that are available in the API are available as function calls, for example to get all users:

$client->users()->all()

Filtering

You can filter on records:

$calls = $client->callDetailRecords()->all([
    'filters' => [
        'leadId' => [
            '$eq' => 652840661
        ]
    ]
]);

info

See all filters here

caution

The all method will put json_encode() around the filters by default

Sorting

To sort on a field on the resource:

$client->users()->all([
    'sortProperty' => 'email',
    'sortDirection' => 'DESC'
]);

Pagination

You can limit the results:

$client->leads()->all([
    'pageSize' => 50
]);

info

See all pagination options here

Manual requests

If for some reason you need to do a manual request:

$client->get('users') // Raw get request to /users
$client->request('GET', 'users') // Alternative way

public function request(string $method, string $url, array $args = []): ResponseInterface
public function get(string $url, array $args = []): array
public function post(string $url, array $args = []): array
public function put(string $url, array $args = []): array
public function patch(string $url, array $args = []): array
public function delete(string $url, array $args = []): array

caution

When doing custom get requests, make sure to json_encode the filters, for example:

$client->get('endpoint', ['filters' => json_encode($filters)])

Resource examples

Not all resources are documented here, as most of them share the same code base.

At this time of writing, you can call the following resources:

$client->
    organization()
    leads()
    users()
    campaigns()
    projects()
    campaignFields()
    sessions()
    products()
    notes()
    sales()
    contacts()
    callDetailRecords() // or cdr()
    fields()
    fieldMappings()
    pools()
    imports()
    mails()

Leads

To get all leads you can use:

$client->leads()->all()

You can also use an existing view/filter to limit only relevant leads, for example:

$client->leads()->all([
    'pageSize' => 50,
    'id' => 203196, // ID of the filter (e.g.: https://app.adversus.io/warehouse-leads?id=203196)
]);

To find a lead by ID:

$lead = $client->leads()->find(652840661);

Contacts

Let's say you want to find the contact that is linked to a Lead:

$lead = $client->leads()->find(652840661);
$contact = $client->contacts()->find($lead['contactId']);

What you will see is that the data array contains the fields, however the fields are not mapped yet.

For this reason, you can call the following method:

$contact = $client->contacts()->findAndMapFields($lead['contactId']);

This will append a mapped array with the mapped fields.

Full example

Let's say you want to sync the lead information to a local system.

We can take the steps below to achieve this.

Step 1: retrieve the leads

$leads = $client->leads()->all([
    'pageSize' => 50,
    'id' => 203196, // ID of the filter (e.g.: https://app.adversus.io/warehouse-leads?id=203196)
]);
        
foreach ($leads as $lead) {
    dd($lead);
}

array:19 [
  "id" => 674942882
  "campaignId" => 59268
  "contactId" => 549772169
  ...
  "status" => "automaticRedial"
  "active" => false
  "externalId" => null
  "import_id" => "2665860"
  "masterData" => array:10 [
    0 => array:3 [
      "id" => 65487
      "label" => "Bedrijf"
      "value" => "Praktijk voor ..."
    ]
  ]
  "resultData" => array:1 [
    0 => array:3 [
      "id" => 68488
      "label" => "Bijzonderheden"
      "value" => """
        395.00
        hoofdkantoor hilversum : 
        """
    ]
  ]
]

Step 2: retrieve the contact information

$lead = $client->leads()->find(652840661);
$contact = $client->contacts()->findAndMapFields($lead['contactId']);
dd($contact);

array:6 [
  "id" => 518569024
  "poolId" => 56749
  "importId" => 2514500
  ...
  "mapped" => array:33 [
    "AHDNR" => "ADH000000AABCBD"
    "Bedrijf" => "Company name"
    "STRAAT" => "Lorem ipsum street"
    "HUISNR" => "1"
    "POSTCODE" => "2871AS"
    "WOONPLAATS" => "Groningen"
    "GEMEENTE" => "KRIMPENERWAARD"
    "TELNR" => "0182-xxxxx"
    "EMAIL" => "email@example.com"
    "URL" => "https://www.ah.nl/winkel/xxxx"
    "RECHTSVORM" => "Besloten Vennootschap (BV)"
    "OMSHOOFDACT" => "4711 Supermarkten en dergelijke winkels...."
    ...
    "Note to agent" => "Goed!!"
    "EMAIL op site" => "another@ah.nl"
    "Bijzonderheden" => """
      BGNL- €123,=
      PLAATSEN VIA MEDIASTAD
      """
    "BTW nummer" => "NL002230XXXXXX"
    "Product" => "Bedrijvengids-NL STANDAARD (399)"
    "QA Status" => "Approved"
    "Original Campaign Name" => "Upsell Campaign (Royal-Sales)"
    "Original User Name" => "Lorem Mans"
    "Callcenter" => "Dichtbij Baantje"
    "KvK" => "3501XXXX"
    "SBIHOOFDACT" => "4711"
    "Original Campaign ID" => "58041"
    "Original User ID" => "207708"
    ...
  ]
]

Step 3: retrieve the user information

$user = $client->users()->find(207708);
dd($user);

array:17 [
  "id" => 207708
  "name" => "Lorem Buns"
  "displayName" => "Lorem Buns"
  "type" => "internal"
  "navn" => "Lorem Buns"
  "active" => true
  "admin" => false
  "phone" => "+311234"
  "email" => "lorem@ipsum.com"
  "locale" => "en_GB"
  "timezone" => null
  "teams" => array:6 [
    0 => "zelf nummers invoeren"
    ...
  ]
  "memberOf" => array:6 [
    0 => array:2 [
      "id" => 15160
      "name" => "zelf nummers invoeren"
    ]
    ...
  ]
  "group" => array:2 [
    "id" => 1144
    "name" => "Dichtbij Baantje"
  ]
  "role" => array:2 [
    "id" => 32042
    "name" => "Test Jos"
  ]
  "profileUrl" => "https://adversus-profiles.s3.gra.io.cloud.ovh.net/.....jpg"
]

Step 4: retrieve additional lead data

Get the calls:

$calls = $client->callDetailRecords()->all([
    'filters' => [
        'leadId' => [
            '$eq' => 652840661
        ]
    ]
]);

foreach ($calls as $call) {
    dd($call);
}

array:16 [
  "id" => 749698918
  "sessionId" => 732726021
  "userId" => 207708
  "campaignId" => 58041
  "leadId" => 652840661
  "durationSeconds" => 37
  "conversationSeconds" => 21
  "destination" => "+31182381001"
  "disposition" => "answered"
  "startTime" => "2023-10-04T13:12:00Z"
  "answerTime" => "2023-10-04T13:12:17Z"
  "endTime" => "2023-10-04T13:12:38Z"
  "insertedTime" => "2023-10-04T13:12:38Z"
  "type" => "outbound"
  "upload" => "uploaded"
  "links" => array:1 [
    "recording" => "https://api.adversus.io/v1/cdr/749698918/recording"
  ]
]

To download the recording:

foreach ($calls as $call) {
    $recordingFile = $client->callDetailRecords()->getRecording($call['id']);
    file_put_contents(
        public_path('recording.mpeg'),
        $recordingFile->getBody()->getContents()
    );
    
    // File saved in public/recording.mpeg
}

Upgrade Guide

To upgrade this module:

composer update qore/adversus