Publisher Article API

Authorization

Include Authorization: Bearer <apikey> header in your requests.

Error handling

Every request can return an error in its context:

{
  "result": "error",
  "message": "Title is not set or is too short"
}

WebHooks

You can subscribe to notifications on article status change. Everytime article status changes (waiting/ready/processing/deleted/…), our server will send a POST request to your webhook endpoint with body:

{
    "id": "cc35e0996a2e8e449d21d6b646678e7e",
    "status": "ready",
    "title": "Kreisstadt wird bis 2030 weiterwachsen",
    "webhook_id": 42
}

webhook_id variable is meant to be autoincremented. it can never be the same, also it can never decrease.

We won’t check for response code of your webhook, and we won’t resend this call if your endpoint didn’t respond.

At the moment we don’t have webinterface for this kind of webhooks, but if you want to use this feature please ask BotTalk Support to enable webhooks on your project. Please be ready to provide endpoint URL, that will receive webhooks.

Get article list

Request: GET https://bottalk.io/api/articles?limit=20&offset=10

Optional parameters:

  • limit=[int] – limits number of results
  • offset=[int] – offset of the results if they are limited

Response:

{
  "result": "ok",
  "count": 2,
  "articles": [
    {
      "id": "b49f2511d9033f313b8c0d361687cd5f",
      "title": "Test title 2",
      "text": "Test text 55",
      "added": 1573132925,
      "status": "no_money",
      "url": "https://test.de/article.html"     
    },
    {
      "id": "90ae27149dba7f5fbf4269b9318ba9cb",
      "title": "Test title 5",
      "text": "Test text 09",
      "added": 1573133305,
      "status": "ready",
      "audio": "https:\/\/bottalk.io\/audio\/d67e6dd172ab320880a158fd17fcf4f4.mp3",
      "url": null     
    }
  ]
}

Possible article statuses:

  • ready - the article is ready, and audiofile exists
  • rejected - the article is rejected by type
  • waiting - the article is waiting to be audified
  • processing - the audification is in progress
  • enrich - the article is waiting to be processed by Comprehend
  • enrich:progress - the article is being processed by Comprehend
  • enrich:failed - Comprehend failed with unknown reasons
  • errored - some unpredicted error happened, we can’t proceed with this article

Get a single article

Request: GET https://bottalk.io/api/articles/{id}

Response:

{
  "result": "ok",
  "article": {
    "id": "90ae27149dba7f5fbf4269b9318ba9cb",
    "title": "Test title 5",
    "text": "Test text 09",
    "added": 1573133305,
    "status": "ready",
    "url": "https://test.de/article.html",     
    "type": [
                 {
                   "Name": "TYPE_NACHRICHT",
                   "Score": 0.20319999754428864
                 },
                 {
                   "Name": "TYPE_KOMMENTAR",
                   "Score": 0.14839999377727509
                 },
                 {
                   "Name": "TYPE_LIVE_TICKER",
                   "Score": 0.12219999730587006
                 }
           ],
    "audio": "https:\/\/bottalk.io\/audio\/d67e6dd172ab320880a158fd17fcf4f4.mp3"
  }
}

Add article

Request: POST https://bottalk.io/api/articles

Body:

{
	"title": "Test title 2",
	"text": "Test text 55",
	"url": "https://test.de/article.html",
	"parse": true,
	"labels": [
	    "label1",
	    "label2",
	    "label 3"
	]
}
  • parse key is optional. If parse key is set, the article will be cleaned from HTML tags.
  • url key is optional. If url key is set, the article will save this url, and it will be available in QA forms.
  • labels key is optional. If labels key is set and contains array which is not empty, the article will use that set as a labels for the article.

Response:

{
  "result": "ok",
  "id": "b49f2511d9033f313b8c0d361687cd5f"
}

Update article

Request: PUT https://bottalk.io/api/articles/{id}

Body:

{
	"title": "Test title 99",
	"text": "Test text 55",
	"url": "https://test.de/article.html",
	"labels": [
	    "label 3",
	    "label 4",
	    "label 5"
	]
}
  • url key is optional. If url key is set, the article will save this url, and it will be available in QA forms.
  • labels key is optional. If labels key is set and contains array which is not empty, the article will use that set as a labels for the article.

Response:

{
  "result": "ok",
  "id": "b49f2511d9033f313b8c0d361687cd5f"
}

Delete article

Request: DELETE https://bottalk.io/api/articles/{id}

Response:

{
  "result": "ok"
}