# AntBot API

**Ant BOT API**\
**Integration and Usage from Third-Party Applications**

**Purpose**

* Allows the use of Alice from third-party applications. It is a mandatory requirement that Alice is registered and has a trial period through AntBuddy onboarding.
* Allows running campaigns from third-party applications.
* Creates alarms for a contact (appointments).

#### API Details

All API requests to the Alice system:

* Endpoint: <https://alice.antbuddy.com/rest-api>

**Authorization Header (required)**:

* `Authorization: Bearer {access token}`

#### Get Access Token

* **Endpoint**: `/get-token/`
* **Method**: `POST`
* **Body**:

```json
jsonCopyEdit{
  "username": "username",
  "password": "password"
}
```

* **Description**:
  * **Username**: The username or email created on AntBuddy.
  * **Password**: The password.

#### Campaigns

**Check existing campaigns**

* **Survey Template**: `/rest-api/campaigns/`
* **Method**: `GET`
* **Params**:

```json
jsonCopyEdit{
  "name": "NESHB",
  "phonebook": "732",
  "status": "1"
}
```

* **Description**:
  * **name**: Search by name.
  * **phonebook**: Search by phonebook.
  * **status**: Search by campaign status.\
    1: Started\
    2: Waiting\
    3: Paused\
    4: Ended\
    5: Completed

#### Configure call flow for campaigns

**Survey**\
**Create Survey Template**

* **Endpoint**: `/rest-api/survey-template/`
* **Method**: `POST`
* **Body**:

```json
jsonCopyEdit{
  "name": "Survey Name",
  "tts_language": "vi",
  "description": "anything"
}
```

* **Description**:
  * **name**: The name of the survey template.
  * **tts\_language**: The language of the survey template.\
    `vi`: Vietnamese\
    `en`: English
  * **description**: Description of the survey template.

**Check existing survey templates**

* **Survey Template**: `/rest-api/survey-template/`
* **Method**: `GET`
* **Params**:

```json
jsonCopyEdit{
  "search": "template name",
  "description": "description",
  "is_onboarding": "true",
  "user": "203"
}
```

* **Description**:
  * **search**: Search by name.
  * **description**: Search by description.
  * **is\_onboarding**: (Not specified in the document, but could refer to whether it's part of the onboarding process)
  * **user**: Search by user ID.

**Create Section Template**

* **Endpoint**: `/rest-api/section-template/`
* **Method**: `POST`
* **Body**:

```json
jsonCopyEdit{
  "type": 1,
  "survey": "survey ID",
  "question": "Section Name",
  "script": "IVR Content"
}
```

**Update Section**

* **Endpoint**: `/rest-api/section-template/{id}/`
* **Method**: `PUT`
* **Body**:

```json
jsonCopyEdit{
  "script": "Please wait a moment."
}
```

#### Phonebook & Contact

**Check existing phonebook**

* **Phonebook**: `/rest-api/phonebook/{id}`
* **Method**: `GET`
* **Params**:

```json
jsonCopyEdit{
  "search": "name"
}
```

* **Description**:
  * **search**: Search by phonebook name.

**Check existing contact**

* **Contact**: `/rest-api/contact/{id}`
* **Method**: `GET`
* **Params**:

```json
jsonCopyEdit{
  "phonebook": "732",
  "search": "0934523423"
}
```

* **Description**:
  * **phonebook**: Search by phonebook ID.
  * **search**: Search by phone number or name.

**Create Phonebook**

* **Create Phonebook**: `/rest-api/phonebook/`
* **Method**: `POST`
* **Body**:

```json
jsonCopyEdit{
  "name": "Phonebook Name",
  "description": "Phonebook Description" (optional)
}
```

* **Description**:
  * **name**: The name of the phonebook.
  * **description**: The description of the phonebook (optional).

**Update Phonebook**

* **Update Phonebook**: `/rest-api/phonebook/{id}/`
* **Method**: `PUT`
* **Body**:

```json
jsonCopyEdit{
  "name": "Changed Name",
  "description": "Updated Description"
}
```

* **Description**:

  * **name**: Change the name of the phonebook.
  * **description**: Change the description of the phonebook.

**Create Contact**

* **Create single contact**
  * **Create**: `/rest-api/contact/`
  * **Method**: POST
  * **Body**:

    ```json
    jsonCopyEdit{
      "phonebook": {phonebook_id} (required),
      "contact": "0934890883" (required),
      "email": "linh.huynh@htklabs.com" (optional),
      "last_name": "Huynh" (optional),
      "first_name": "Linh" (optional),
      "description": "ABC customer" (optional),
      "status": 1 or 0 (1: active, 0: inactive) (required),
      "additional_vars": "{\"params_1\":\"123456\",\"params_2\":\"123456\"}" (optional)
    }
    ```
* **Update contact based on ID**
  * **Update**: `/rest-api/contact/{id}/`
  * **Method**: PUT
  * **Body**:

    ```json
    jsonCopyEdit{
      "contact": "0934890884",
      "status": 1,
      "country": "VN",
      "first_name": "A",
      "last_name": "B"
    }
    ```
* **Create multiple contacts**
  * **Endpoint**: `/rest-api/bulkcontact/`
  * **Method**: POST
  * **Body**:

    ```json
    jsonCopyEdit{
      "phonebook": 293,
      "contacts": [
        {
          "contact": "0934890883",
          "email": "linh.huynh@htklabs.com",
          "last_name": "Huynh",
          "first_name": "Linh",
          "status": 1
        },
        {
          "contact": "0934890881",
          "email": "linh.huynh@htklabs.com",
          "last_name": "Huynh",
          "first_name": "Linh",
          "status": 1
        }
      ]
    }
    ```

***

#### Create Call Campaign

* **Check available gateways**
  * **Gateway List**: `/rest-api/gateway/`
  * **Method**: GET
  * **Response**:

    ```json
    jsonCopyEdit{
      "results": [
        {
          "id": 23,
          "name": "AliceDevGateway",
          "status": 1,
          "description": "AliceDevGateway",
          "addprefix": "",
          "removeprefix": "",
          "gateways": "sofia/gateway/AliceDevGateway/",
          "subdomain": "company",
          "gateway_codecs": "",
          "gateway_timeouts": "10",
          "gateway_retries": "",
          "originate_dial_string": "",
          "secondused": null,
          "created_date": "2019-12-26T04:17:12.673711Z",
          "updated_date": "2020-01-14T03:12:27.079710Z",
          "addparameter": "",
          "count_call": 0,
          "count_in_use": null,
          "maximum_call": null,
          "is_trial": true,
          "failover": null
        }
      ]
    }
    ```
* **Create Campaign**
  * **Endpoint**: `/rest-api/campaigns/`
  * **Method**: POST
  * **Body Example**:

    ```json
    jsonCopyEdit{
      "name": "rest-api-cp-2",
      "description": "rest api for campaign",
      "callerid": "lh",
      "phonebook": [
        293
      ],
      "aleg_gateway": 23,
      "object_id": 351,
      "frequency": 10,
      "startingdate": "2020-02-11T02:36:39.045000Z",
      "expirationdate": "2020-02-12T02:36:39.045000Z",
      "daily_start_time": "08:00:00",
      "daily_stop_time": "21:00:00"
    }
    ```
  * **Description**:
    * `name`: required
    * `description`: rest API for campaign (optional)
    * `callerid`: caller name when calling out (optional)
    * `phonebook`: phone book IDs list (required)
    * `aleg_gateway`: gateway dial-out (required)
    * `object_id`: survey template application (required)
    * `frequency`: calls per minute (required)
    * `startingdate`: starting date for the campaign (required)
    * `expirationdate`: stopping date for the campaign (required)
    * `daily_start_time`: daily start time (required)
    * `daily_stop_time`: daily stop time (required)

***

#### Update Call Campaign

* **Update Campaign**
  * **Endpoint**: `/rest-api/campaigns/{id}/`
  * **Method**: PUT
  * **Body**:

    ```json
    jsonCopyEdit{
      "name": "rest-api-cp-2",
      "description": "rest API for campaign",
      "callerid": "rest_api",
      "phonebook": [
        293
      ],
      "frequency": 3,
      "startingdate": "2020-02-11T02:36:39.045000Z",
      "expirationdate": "2020-02-12T02:36:39.045000Z",
      "daily_start_time": "09:00:00",
      "daily_stop_time": "18:00:00"
    }

    ```

**Change Status of Call Campaign**

* **Endpoint**: `/rest-api/campaigns/{id}/status/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "status": 1
  }
  ```
* **Description**:
  * **START** = 1
  * **PAUSE** = 2
  * **ABORT** = 3
  * **END** = 4

***

#### Delete Call Campaign

* **Endpoint**: `/rest-api/campaigns/{id}`
* **Method**: DELETE

***

#### Appointment

**Survey List**

* **Check the list of surveys**
  * **Endpoint**: `/rest-api/survey-list/`
  * **Method**: GET
  * **Params**:

    ```json
    jsonCopyEdit{
      "search": "test",
      "tts_language": "vi",
      "description": "Test",
      "campaign": 1243
    }
    ```
* **Description**:
  * **search**: Search by name
  * **tts\_language**: Search by language
    * `vi`: Vietnamese
    * `en`: English
  * **description**: Search by description
  * **campaign**: Search by campaign ID

**DNC (Do Not Call)**

* **Check DNC List**
  * **Endpoint**: `/rest-api/dnc-list/`
  * **Method**: GET
* **Check DNC Contact**
  * **Endpoint**: `/rest-api/dnc-contact/`
  * **Method**: GET
* **Add to DNC List**
  * **Endpoint**: `/rest-api/dnc-list/`
  * **Method**: POST
  * **Body**:

    ```json
    jsonCopyEdit{
      "name": "name dnc",
      "description": "test"
    }
    ```
* **Description**:
  * **name**: DNC name
  * **description**: Description
* **Add to DNC Contact**
  * **Endpoint**: `/rest-api/dnc-contact/`
  * **Method**: POST
  * **Body**:

    ```json
    jsonCopyEdit{
      "phone_number": "0324324343",
      "dnc": "343"
    }
    ```
* **Description**:
  * **phone\_number**: Phone number
  * **dnc**: DNC list ID

**Report**

* **Check Report**
  * **Endpoint**: `/rest-api/cdr/`
  * **Method**: GET
  * **Params**:

    ```json
    jsonCopyEdit{
      "callid": "res232-fsf3-sfdsf",
      "callerid": "admin",
      "phone_number": "094343434",
      "from_date": "2023-04-06T10:52:56.162517Z",
      "to_date": "2023-03-28T08:05:07.495988Z",
      "duration": 34,
      "billsec": 3,
      "disposition": "FAILED",
      "hangup_cause": "UNALLOCATED_NUMBER",
      "sip_term_status": 404,
      "sip_term_cause": 2,
      "endpoint_disposition": "ANSWER",
      "campaign": 23,
      "alarm": false,
      "otp": true
    }
    ```
* **Description**:
  * **callid**: Call ID
  * **callerid**: Caller ID
  * **phone\_number**: Phone number
  * **from\_date**: Start time
  * **to\_date**: End time
  * **duration**: Call duration
  * **billsec**:
  * **disposition**:
  * **hangup\_cause**: Reason for call termination
  * **sip\_term\_status**:
  * **sip\_term\_cause**:
  * **endpoint\_disposition**:
  * **campaign**: Campaign ID
  * **alarm**: Reminder calls
    * `true`: Reminder calls
    * `false`: Non-reminder calls
  * **otp**: OTP calls
    * `true`: OTP calls
    * `false`: Non-OTP calls

***

**Subscribers**

* **View campaign members**
  * **Get Subscribers**: `/rest-api/subscriber-list/`
  * **Method**: GET
  * **Params**:

    ```json
    jsonCopyEdit{
      "campaign": 2323,
      "contact": "094344334",
      "status": 2,
      "duration": 43,
      "billsec": 23
    }
    ```
* **Description**:
  * **campaign**: Campaign ID
  * **contact**: Phone number
  * **status**: Status
  * **duration**: Call duration
  * **billsec**:

***

#### Calendar

**Set up Calendar**

* **Endpoint**: `/rest-api/calendar-setting/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "label": "rest-api-cp-2",
    "callerid": "mantest_calendarsettings",
    "caller_name": "",
    "call_timeout": 60,
    "survey": 953,
    "aleg_gateway": 23
  }
  ```
* **Description**:
  * **label**: Name (required)
  * **callerid**: Caller display (optional)
  * **caller\_name**: Caller name (optional)
  * **call\_timeout**: Timeout duration in seconds (required)
  * **survey**: Survey ID (required) - Get from Survey List API
  * **aleg\_gateway**: Outbound gateway (required) - Get from Gateway List API

**Calendar User**

* **Endpoint**: `/rest-api/calendar-user/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "username": "cal-rest-user-resp2",
    "password": "12345678",  // required
    "calendar_setting": 4   // required
  }
  ```
* **Description**:
  * **username**: User login (required)
  * **calendar\_setting**: Calendar setting, Get from calendar-setting API

**Create Calendar**

* **Endpoint**: `/rest-api/calendar/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "name": "linh-calendar-rest",
    "user": 5  // required
  }
  ```
* **Description**:
  * **name**: required
  * **user**: Calendar User List, Get from calendar-user API

**Create Event**

* **Endpoint**: `/rest-api/event/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "title": "today-linhhv",
    "description": "",
    "start": "2020-02-15T09:30:39.177000Z",
    "end": "2020-02-15T10:13:39.177000Z",
    "creator": 115,
    "calendar": 7
  }
  ```
* **Description**:
  * **title**: Event title (required)
  * **start**: Start time (required)
  * **end**: End time (required)
  * **creator**: Calendar user assigned to it, get from calendar-user API
  * **calendar**: Calendar assigned to the event, get from calendar API

**Create Alarm**

* **Endpoint**: `/rest-api/alarm/`
* **Method**: POST
* **Body**:

  ```json
  jsonCopyEdit{
    "alarm_phonenumber": "0934890883",
    "date_start_notice": "2020-02-12T02:49:33.572Z",
    "phonenumber_transfer": "",
    "event": 8
  }
  ```
* **Description**:
  * **alarm\_phonenumber**: Call to number (required)
  * **date\_start\_notice**: Starting date for alarm (optional - default is current time)
  * **phonenumber\_transfer**: Transfer phone number (optional)
  * **event**: Related event (required), event list from event API, method GET