Developers

API v1 (Beta) - Reference

Introduction

This is the documentation for version 1.0 of the API. Last updated on 21 January, 2025.

Authentication

Authentication to the platform is possible by accessing your admin profile and navigating to the “settings” page in the API Keys section. You can generate up to 5 API keys to interact with your Chatbots and your conversations from external platforms.

To interact with the API, you need to authenticate by providing a Consumer Key and a Consumer Secret in the authorization header of each request. The keys can be generated through the platform in the admin section.

Example of authorization header:

Authorization: ck_your-consumer-key:sk_your-consumer-secret

Send Message

This API allows you to send a new message and a conversation_id to attribute a message to the conversation. If the conversation_id is null, a new conversation will be created and a conversation_id will be assigned, which will be returned in the response.

Endpoint

POST https://app.artiko.ai/wp-json/send-message/v1/ask

Headers

Authorization: ck_your-consumer-key:sk_your-consumer-secret
Content-Type: application/json

Request Body

The request body should be a JSON object with the following properties:

{
  "chatbot_id": "string",
  "user_message": "string",
  "conversation_id": "string"
}
  • chatbot_id: The ID of the chatbot you want to interact with. This can be found in the Chatbots section of the platform, in the upper right corner of each listed chatbot.
  • user_message: The message you want to send to the chatbot.
  • conversation_id: The ID of the conversation. If this is a new conversation, send "0" or an empty string. A new conversation_id will be generated and returned in the response.

Response

The response will be a JSON object with the following structure:

{
  "success": true,
  "conversation_id": "string",
  "chatbot_message": "string"
}
  • success: A boolean indicating whether the request was successful.
  • conversation_id: The ID of the conversation. If this was a new conversation, this will be the newly generated ID.
  • chatbot_message: The response message from the chatbot.

Example cURL Request

curl -X POST \
https://app.artiko.ai/wp-json/send-message/v1/ask \
-H 'Authorization: ck_your-consumer-key:sk_your-consumer-secret' \
-H 'Content-Type: application/json' \
-d '{
  "chatbot_id": "example_chatbot_id",
  "user_message": "What is the meaning of life?",
  "conversation_id": "example_conversation_id"
}'

Assistants Overview

The endpoints below allow you to manage your Chatbots (also referred to as Assistants), including creating new ones, updating existing ones, listing them, and deleting them.

Create Chatbot

Creates a new chatbot with the specified parameters. The user must be authenticated and have a valid API key.

Endpoint

POST /artiko/v1/create-chatbot

Headers

Authorization: ck_your-consumer-key:sk_your-consumer-secret
Content-Type: application/json

Request Body

Example of JSON parameters:

{
  "chatbot_name": "My Chatbot",
  "chatbot_description": "A friendly assistant",
  "use_knowledge": 1,
  "knowledge_folders": 12,
  "model": "gpt-3.5-turbo",
  "temperature": 0.5,
  "system_prompt": "You are a helpful AI.",
  "membri_staff_id": "NULL",
  "use_plugins": 0,
  "active_plugin_id": null
}
  • chatbot_name (string, obbligatorio): Nome del chatbot
  • chatbot_description (string): Descrizione del chatbot
  • use_knowledge (int): Flag per indicare se usare Knowledge Base (0 o 1)
  • knowledge_folders (int|nullable): ID della cartella di knowledge
  • model (string, obbligatorio): Modello usato dal chatbot (es. "gpt-3.5-turbo")
  • temperature (float): Valore di temperatura per la generazione delle risposte
  • system_prompt (string): Prompt di sistema
  • membri_staff_id (string): ID staff associato
  • use_plugins (int): Indica se abilitare l’uso plugin (0 o 1)
  • active_plugin_id (int|nullable): ID plugin attivo

Response

{
  "message": "Chatbot creato con successo",
  "chatbot_id": 123,
  "data": {
    "...": "campi inviati"
  }
}

chatbot_id restituisce l’ID univoco del nuovo chatbot creato.

Update Chatbot

Aggiorna le proprietà di un chatbot esistente. Il chatbot deve già esistere e appartenere all’utente autenticato.

Endpoint

POST /artiko/v1/update-chatbot

Headers

Authorization: ck_your-consumer-key:sk_your-consumer-secret
Content-Type: application/json

Request Body

Struttura esempio:

{
  "chatbot_id": "123",
  "system_prompt": "New system prompt",
  "temperature": 0.7
}
  • chatbot_id (int): L’ID del chatbot da aggiornare
  • system_prompt (string): Prompt di sistema aggiornato
  • temperature (float): Nuovo valore di temperatura

Response

{
  "message": "Chatbot aggiornato con successo",
  "chatbot_id": 123
}

Delete Chatbot

Elimina un chatbot esistente, verificando che appartenga all’utente autenticato.

Endpoint

POST /artiko/v1/delete-chatbot

Headers

Authorization: ck_your-consumer-key:sk_your-consumer-secret
Content-Type: application/json

Request Body

Esempio:

{
  "chatbot_id": 123
}
  • chatbot_id (int): L’ID del chatbot da eliminare

Response

{
  "message": "Chatbot eliminato con successo",
  "deleted_id": 123
}

List Chatbots

Restituisce la lista dei chatbot appartenenti all’utente autenticato.

Endpoint

POST /artiko/v1/list-chatbots

Headers

Authorization: ck_your-consumer-key:sk_your-consumer-secret
Content-Type: application/json

Request Body

Non sono richiesti parametri aggiuntivi oltre all’autenticazione. (Alcune installazioni potrebbero richiedere un body vuoto {} per forzare la chiamata POST).

Response

Restituisce un array di chatbot con i campi principali. 

{
  "message": "Chatbot recuperati con successo",
  "chatbots": [
    {
      "chatbot_id": 123,
      "chatbot_name": "My Chatbot",
      "chatbot_description": "A friendly assistant",
      "use_knowledge": 1,
      "knowledge_folders": 12,
      "model": "gpt-3.5-turbo",
      "temperature": 0.5,
      "system_prompt": "You are a helpful AI.",
      "use_plugins": 0,
      "active_plugin_id": null
    },
    ...
  ]
}