Documentation Powered by ReDoc

KODA.AI API (1.2.3)

Download OpenAPI specification:Download

E-mail: developers@koda.ai

Authentication

OAuth

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://api.eu-pl.koda.ai/oauth/token
Scopes:
  • inbox:read -

    get available conversations

  • inbox:modify -

    enable/disable moderator mode and send block/attachment/reply

  • knowledge_base:read -

    search and retrieve knowledge base documents

  • knowledge_base:modify -

    create, update, and delete knowledge base documents

  • knowledge_base:parser -

    parse websites and extract content for knowledge base documents

Voice Outbound API

Using this API You can automate gathering information from users via voicebots.

List of calls

Returns a list of call list

Authorizations:
OAuth (outbound:read)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
query Parameters
page
number
Default: 1
Example: page=3
on_page
number
Default: 20
Example: on_page=3
sort_order
string
Default: "DESC"
Enum: "ASC" "DESC"
sort_by
string
Default: "created_at"
Enum: "name" "start_at" "status" "created_at" "created_via" "processed_at" "total_calls" "finished_calls"
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": [
    ]
}

Create call list

Create call list

Authorizations:
OAuth (outbound:create)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>
Request Body schema: application/json

Data of new call list to be created

name
required
string
allowed_hours_start
required
string

Allowed calling time (start)

allowed_hours_end
required
string

Allowed calling time (end)

caller_phone_number
required
string
start_block_id
required
string

You can get block id from dashboard`s URL: app.kodabots.com/bot/{bot_id}/create-bot/{block_id}

report_vars
Array of strings

Vars will be visible data in the report but it will not influence on call status.

campaign_vars
required
Array of strings

When the user has filled all the above variables, the call is marked as data_collected in the analytics report.

max_attempts
required
number

Number of calls retries

attempts_delay
required
number

Interval between consecutive trials (in hours). Voicebot rings again in allowed hours when the user does not answer the phone, the line is busy or voicemail is detected

campaign_date_start
required
string

Voicebot don`t make calls before this date

campaign_date_time
required
string
campaign_date_end
string

Voicebot doesn`t make calls after this date. It`s useful when input data are valid only in a specific amount of time e.g. voicebot daily collect information about packages status

campaign_date_time_end
string
campaign_allowed_days
Array of strings

In with week days voicebot can make calls (ISO week date): 1-Monday; 2-Tuesday; 3-Wednesday; 4-Thursday; 5-Friday; 6-Saturday; 0-Sunday

required
Array of objects

List of calls to make.

Responses

Request samples

Content type
application/json
{
  • "name": "name",
  • "allowed_hours_start": "14:30",
  • "allowed_hours_end": "22:30",
  • "caller_phone_number": "+48222431496",
  • "start_block_id": "5d306675-4500-409d-80a2-6d16ac28db58",
  • "report_vars": [
    ],
  • "campaign_vars": [
    ],
  • "max_attempts": 3,
  • "attempts_delay": 3,
  • "campaign_date_start": "2014-06-03",
  • "campaign_date_time": "14:30",
  • "campaign_date_end": "2014-07-03",
  • "campaign_date_time_end": "19:30",
  • "campaign_allowed_days": [
    ],
  • "calls": [
    ]
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Call list report

Authorizations:
OAuth (outbound:read)
path Parameters
listId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Resume calling

Resume calling on call list

Authorizations:
OAuth (outbound:resume)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
listId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Pause calling

Pause calling on call list

Authorizations:
OAuth (outbound:pause)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
listId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Inbox API

List of chats

Returns a list of chats

Authorizations:
OAuth (inbox:read)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
query Parameters
page
number
Default: 1
Example: page=3
on_page
number
Default: 20
Example: on_page=3
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": [
    ]
}

Get single chat

Get single chat

Authorizations:
OAuth (inbox:read)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string
query Parameters
page
number
Default: 1
Example: page=3
on_page
number
Default: 20
Example: on_page=3
from
number <timestamp>
to
number <timestamp>
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": [
    ]
}

Enable moderator mode

Enable moderator mode

Authorizations:
OAuth (inbox:readinbox:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": true
}

Sent moderator message

Sent moderator message

Authorizations:
OAuth (inbox:readinbox:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string
Request Body schema: application/json
moderator_message
required
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "moderator_message": "string"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": true
}

Disable moderator mode (mark done)

Disable moderator mode (mark done)

Authorizations:
OAuth (inbox:readinbox:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string
Request Body schema: application/json
quiet
boolean

Don`t send the block configured in the chatbot`s settings (dashboard)

message
string <= 1000 characters

Overwrite message set in the dashboard. A Message will be sent to the user

Responses

Request samples

Content type
application/json
{
  • "quiet": false,
  • "message": "From now on, you talk to the chatbot"
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": true
}

Send file attachment

Send file attachment

Authorizations:
OAuth (inbox:readinbox:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string
Request Body schema: multipart/form-data
audio
string <binary>
image
string <binary>
file
string <binary>
video
string <binary>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": true
}

Send block

Send a content block as a bot response to a user, with optionally update user variables

Authorizations:
OAuth (inbox:readinbox:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
platformUserId
required
string
Request Body schema: application/json
block_id
required
string

Block id

object

Optional user variables

Responses

Request samples

Content type
application/json
{
  • "block_id": "f60ea240-4cda-d1f9-032f-05eba5794058",
  • "user_variables": {
    }
}

Response samples

Content type
application/json
{ }

Knowledge Base API

API to manage knowledge base documents for generative AI capabilities.

Search knowledge base documents

Search for relevant documents in the knowledge base

Authorizations:
OAuth (knowledge_base:read)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>
Request Body schema: application/json
search
string

Search query text

object

Responses

Request samples

Content type
application/json
{
  • "search": "password reset",
  • "metadata_filter": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": [
    ]
}

Create knowledge base document

Create a new document in the knowledge base

Authorizations:
OAuth (knowledge_base:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>
Request Body schema: application/json
title
required
string <= 120 characters
content
required
string
object
tags
Array of strings

Tags for the document. Will be converted to metadata with lowercase and underscores (e.g. 'Product Guide' becomes 'product_guide': 'yes')

auto_publish
boolean
Default: false

Automatically publish new version with changes. Otherwise, it will added to draft and user new approve changes in the dashboard.

chunk_size
integer [ 100 .. 1000 ]

Chunk size for splitting the document into smaller parts. This is useful for large documents to improve searchability.

Responses

Request samples

Content type
application/json
{
  • "title": "Product Documentation",
  • "content": "This is the content of the knowledge base document.",
  • "metadata": {
    },
  • "tags": [
    ],
  • "auto_publish": true,
  • "chunk_size": 500
}

Response samples

Content type
application/json
{
  • "doc_id": "3337eb37-9c70-4e88-a173-21372501d7ee",
  • "title": "Product Documentation",
  • "content": "This is the content of the knowledge base document.",
  • "meta": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Parse website content

Extract and process content from a website URL for knowledge base ingestion

Authorizations:
OAuth (knowledge_base:parser)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>
Request Body schema: application/json
url
required
string <uri>

URL of the website to parse

selector
string
Default: "body"

Optional CSS selector to target specific content on the page

chunk_mode
string
Default: "html"
Enum: "selector" "html" "text"

Method to use for chunking content. 'selector' uses the provided CSS selector, 'html' splits content based on HTML semantic structure (headings, paragraphs, etc.), while 'text' extracts readable content and then divides it into chunks based on chunk_size.

chunk_size
integer [ 100 .. 1000 ]
Default: 500

Size of content chunks for processing. Used only if chunk_mode is 'text'.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Get knowledge base document

Retrieve a specific document from the knowledge base

Authorizations:
OAuth (knowledge_base:read)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
doc_id
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Update knowledge base document

Update an existing document in the knowledge base

Authorizations:
OAuth (knowledge_base:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
doc_id
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>
Request Body schema: application/json
title
required
string <= 120 characters
content
required
string
object
tags
Array of strings

Tags for the document. Will be converted to metadata with lowercase and underscores (e.g. 'Product Guide' becomes 'product_guide': 'yes')

auto_publish
boolean
Default: false

Automatically publish new version with changes. Otherwise, it will added to draft and user new approve changes in the dashboard.

chunk_size
integer [ 100 .. 1000 ]

Chunk size for splitting the document into smaller parts. This is useful for large documents to improve searchability.

Responses

Request samples

Content type
application/json
{
  • "title": "Product Documentation",
  • "content": "This is the content of the knowledge base document.",
  • "metadata": {
    },
  • "tags": [
    ],
  • "auto_publish": true,
  • "chunk_size": 500
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}

Delete knowledge base document

Remove a document from the knowledge base

Authorizations:
OAuth (knowledge_base:modify)
path Parameters
botId
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
doc_id
required
string <uuid>
Example: 3337eb37-9c70-4e88-a173-21372501d7ee
header Parameters
Authorization
required
string <bearer>
Example: Bearer <Access Token>

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "response": {
    }
}