# Speaky API

## What can I do with API?

You can generate custom links for Voice Pages or import feedback data for a chosen period to third-party systems. 

## Getting the access token

Generate the token [HERE](https://speaky.instreamatic.com/main/accounts/my)

Once generated, copy the token and use it in your future projects.

{% hint style="warning" %}
Please contact your representative to get access to API first.
{% endhint %}

## Custom links via API

### Preparation

* Create a set of parameters to send via your link [HERE](https://speaky.instreamatic.com/main/manage/tag). The parameters are sent as key/vlaue pairs and you are creating a key. 
* Create a new Voice Page or open an existing one.
* Assign a set of tags to a page via the **Tags** screen.

### API Request

**Method:** POST

**Endpoint:** <https://speaky.instreamatic.com/api/v1/product/$PRODUCT\\_ID/link>

**Headers:**

```
Authorization: $ACCOUNT_TOKEN 
Content-Type: application/json
```

**Body:**

```
{"tag1":"value1","tag2":"value2"}
```

Where,&#x20;

* $ACCOUNT\_TOKEN is your access token
* $PRODUCT\_ID is an ID of a Voice Page. For example, in <https://feedback.instreamatic.com/main/manage/product/343/main>, **343** is the ID.
* tag - one of the tags assigned to the page. You can send up to 10 different tags within one request.
* value - value for a tag.

### API Response

```json
{
  "code": 200,
  "message": null,
  "response": {
    "id": 21,
    "link": "https://feedback.instreamatic.com/storage/product/ZRSSUSQM?tag1=value1&tag2=value2",
    "qr_code": {
      "id": 376,
      "meta": {},
      "url": "https://feedback.instreamatic.com/storage/resource/qr/daff2b42c2e6e4259c2838a9b2a22567.png" 
    },
    "tags": [
      {
        "tag_value": "value1",
        "tag": {
          "id": 1,
          "name": "tag1" 
        }
      },
      {
        "tag_value": "value2",
        "tag": {
          "id": 2,
          "name": "tag2" 
        }
      }
    ]
  }
}
```

Where,

* "link" is the customized Voice Page link
* "url" inside the qr\_code is a link to QR-Code with the same link.

## Import feedback via API

### API Request

**Method:** GET

**Endpoint:** <https://speaky.instreamatic.com/api/v1/review?product\\_id=$PRODUCTID\\&from=$STARTDATE\\&to=$END\\_DATE>

**Headers:**

```
Authorization: $ACCOUNT_TOKEN 
```

**Body:**

```
```

Where,&#x20;

* $ACCOUNT\_TOKEN is your access token
* $PRODUCT\_ID is an ID of a Voice Page. For example, in <https://feedback.instreamatic.com/main/manage/product/343/main>, **343** is the ID.
* $STARTDATE - is the period's start date in YYYY-MM-DD format.
* $END\_DATE - is the period's end date in YYYY-MM-DD format.

{% hint style="info" %}
*%Y-%m-%d %H:%M:%S format can be used if you need to retrieve speakys for a narrower period. The deafult timezone is EDT -0400. UNIX Timestamp can be used to avoid the timezone difference.*&#x20;
{% endhint %}

### API Response

```json
{
    "anchor": 835,
        "data": [
        {
            "id": 723,
            "date": "2022-02-18 04:07:40",
            "date_utc": "2022-02-18 01:07:40+00:00",
            "transcript": "How do you speak??",
            "urgent": null,
            "age": "25-34",
            "gender": "M",
            "timezone": "Asia/Calcutta",
            "email": null,
            "country": "IN",
            "geoid": 7279737,
            "tag": []
        }
        ...
    ]
}
```

In case of multiple responses, the system will return the list of responses for the chosen period.

The "anchor" defines the last retrieved speaky. If you want to get only new speakys in your next request, call the following:

**Endpoint:** <https://speaky.instreamatic.com/api/v1/review?product\\_id=$PRODUCTID\\&anchor=$ANCHOR>

where $ANCHOR is an anchor value you got from the previous response. The rest of the headers remains the same.

## How to test the API?

If you are a client, you can create a page and use its parameters and your API-Key to perform tests.&#x20;

If you are not a client yet, please use the following data for the test:

Test page: <https://thespeaky.com/voice/BIXYVKEA/> (use this page to record feedback).

API-Key: 9c0030ae31004cdbea1af75a4fbd1bba

Test tags: test\_tag1 and test\_tag2

Product ID: 169