Typescript (SDK)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.agentConnectors.createAgentConnector({
    id: "<id>",
    createAgentConnectorRequest: {
      provider: "telegram",
      name: "support-bot",
      credentials: {
        botToken: "123456789:replace-with-telegram-bot-token",
      },
      access: {
        mode: "allowlist",
        chatIds: [
          123456789,
        ],
      },
    },
  });

  console.log(result);
}

run();

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.AgentConnectors.CreateAgentConnectorAsync(
    id: "<id>",
    body: MeetKai.MKA1.Types.Components.CreateAgentConnectorRequest.CreateTelegram(
        new CreateTelegramAgentConnectorRequest() {
            Provider = CreateTelegramAgentConnectorRequestProvider.Telegram,
            Name = "support-bot",
            Credentials = new CreateTelegramAgentConnectorRequestCredentials() {
                BotToken = "123456789:replace-with-telegram-bot-token",
            },
            Access = new CreateTelegramAgentConnectorRequestAccess() {
                Mode = CreateTelegramAgentConnectorRequestMode.Allowlist,
                ChatIds = new List<long>() {
                    123456789,
                },
            },
        }
    )
);

// handle response

from meetkai_mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.agent_connectors.create_agent_connector(id="<id>", body={
        "provider": "telegram",
        "name": "support-bot",
        "credentials": {
            "bot_token": "123456789:replace-with-telegram-bot-token",
        },
        "access": {
            "mode": "allowlist",
            "chat_ids": [
                123456789,
            ],
        },
    })

    # Handle response
    print(res)

curl --request POST \
  --url https://apigw.mka1.com/api/v1/agents/{id}/connectors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "telegram",
  "name": "support-bot",
  "credentials": {
    "bot_token": "123456789:replace-with-telegram-bot-token"
  },
  "access": {
    "mode": "allowlist",
    "chat_ids": [
      123456789
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'telegram',
    name: 'support-bot',
    credentials: {bot_token: '123456789:replace-with-telegram-bot-token'},
    access: {mode: 'allowlist', chat_ids: [123456789]}
  })
};

fetch('https://apigw.mka1.com/api/v1/agents/{id}/connectors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/agents/{id}/connectors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'telegram',
    'name' => 'support-bot',
    'credentials' => [
        'bot_token' => '123456789:replace-with-telegram-bot-token'
    ],
    'access' => [
        'mode' => 'allowlist',
        'chat_ids' => [
                123456789
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigw.mka1.com/api/v1/agents/{id}/connectors"

	payload := strings.NewReader("{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/agents/{id}/connectors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/agents/{id}/connectors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent.connector",
  "id": "<string>",
  "agent_id": "<string>",
  "provider": "telegram",
  "name": "<string>",
  "status": "<string>",
  "provider_account_id": "<string>",
  "provider_account_name": "<string>",
  "config": "<unknown>",
  "credentials_configured": true,
  "last_error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

Agent Connectors

Create a connector

Connects the agent to a Telegram bot or WhatsApp Business phone number, validates the provider credentials, and registers the agent’s webhook. WhatsApp connector support is beta. Text, photos, and gateway-supported documents can invoke the agent; inbound media additionally requires write:files. Managed outbound files require read:files, and generated images require both file scopes so their transient provider URLs can be materialized before delivery. The optional write:feedback scope enables native thumbs reaction synchronization to gateway response feedback. These conditional scopes are deliberately not part of x-required-scopes because text-only connectors do not need them. An API key with every listed scope is required; its identity tuple and current scopes are stored as a non-widening ceiling, then revalidated with mk-authentication before every connector run; session and delegated end-user contexts are rejected. The required access policy controls which provider users or chats may invoke the agent.

POST

api

agents

{id}

connectors

Typescript (SDK)

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await sdk.agentConnectors.createAgentConnector({
    id: "<id>",
    createAgentConnectorRequest: {
      provider: "telegram",
      name: "support-bot",
      credentials: {
        botToken: "123456789:replace-with-telegram-bot-token",
      },
      access: {
        mode: "allowlist",
        chatIds: [
          123456789,
        ],
      },
    },
  });

  console.log(result);
}

run();

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using System.Collections.Generic;

var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

var res = await sdk.AgentConnectors.CreateAgentConnectorAsync(
    id: "<id>",
    body: MeetKai.MKA1.Types.Components.CreateAgentConnectorRequest.CreateTelegram(
        new CreateTelegramAgentConnectorRequest() {
            Provider = CreateTelegramAgentConnectorRequestProvider.Telegram,
            Name = "support-bot",
            Credentials = new CreateTelegramAgentConnectorRequestCredentials() {
                BotToken = "123456789:replace-with-telegram-bot-token",
            },
            Access = new CreateTelegramAgentConnectorRequestAccess() {
                Mode = CreateTelegramAgentConnectorRequestMode.Allowlist,
                ChatIds = new List<long>() {
                    123456789,
                },
            },
        }
    )
);

// handle response

from meetkai_mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.agent_connectors.create_agent_connector(id="<id>", body={
        "provider": "telegram",
        "name": "support-bot",
        "credentials": {
            "bot_token": "123456789:replace-with-telegram-bot-token",
        },
        "access": {
            "mode": "allowlist",
            "chat_ids": [
                123456789,
            ],
        },
    })

    # Handle response
    print(res)

curl --request POST \
  --url https://apigw.mka1.com/api/v1/agents/{id}/connectors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "telegram",
  "name": "support-bot",
  "credentials": {
    "bot_token": "123456789:replace-with-telegram-bot-token"
  },
  "access": {
    "mode": "allowlist",
    "chat_ids": [
      123456789
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'telegram',
    name: 'support-bot',
    credentials: {bot_token: '123456789:replace-with-telegram-bot-token'},
    access: {mode: 'allowlist', chat_ids: [123456789]}
  })
};

fetch('https://apigw.mka1.com/api/v1/agents/{id}/connectors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apigw.mka1.com/api/v1/agents/{id}/connectors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'telegram',
    'name' => 'support-bot',
    'credentials' => [
        'bot_token' => '123456789:replace-with-telegram-bot-token'
    ],
    'access' => [
        'mode' => 'allowlist',
        'chat_ids' => [
                123456789
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apigw.mka1.com/api/v1/agents/{id}/connectors"

	payload := strings.NewReader("{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apigw.mka1.com/api/v1/agents/{id}/connectors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apigw.mka1.com/api/v1/agents/{id}/connectors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"telegram\",\n  \"name\": \"support-bot\",\n  \"credentials\": {\n    \"bot_token\": \"123456789:replace-with-telegram-bot-token\"\n  },\n  \"access\": {\n    \"mode\": \"allowlist\",\n    \"chat_ids\": [\n      123456789\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "agent.connector",
  "id": "<string>",
  "agent_id": "<string>",
  "provider": "telegram",
  "name": "<string>",
  "status": "<string>",
  "provider_account_id": "<string>",
  "provider_account_name": "<string>",
  "config": "<unknown>",
  "credentials_configured": true,
  "last_error": "<unknown>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "details": "<unknown>"
  }
}

Authorizations

Authorization

string

header

required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Headers

X-On-Behalf-Of

string

Optional external end-user identifier forwarded by the API gateway.

Path Parameters

string

required

The agent ID.

Body

application/json

Option 1
Option 2

Telegram connector configuration. Creating or activating a connector always discards pending Telegram updates so events from a previous bot binding cannot be delivered to this agent.

provider

enum<string>

required

Telegram Bot API connector. Supports text, photos up to the Bot API's 20 MiB download limit, gateway-supported documents, and response feedback through native thumbs reactions.

Available options:

telegram

credentials

object

required

Show child attributes

access

object

required

The explicit Telegram chat allowlist permitted to invoke the agent.

Show child attributes

name

string

Required string length: 1 - 120

Response

Connector created and activated.

object

enum<string>

required

Available options:

agent.connector

string

required

agent_id

string

required

provider

enum<string>

required

Available options:

telegram,

whatsapp

name

string | null

required

status

string

required

Connector lifecycle status, such as provisioning, activating, active, deleting, or error.

provider_account_id

string

required

The provider account ID: Telegram bot user ID or WhatsApp phone-number ID.

provider_account_name

string | null

required

Provider account display name when one is available.

config

any

required

Arbitrary JSON value.

credentials_configured

boolean

required

Whether encrypted provider credentials are stored for this connector.

last_error

any | null

required

Arbitrary JSON value.

created_at

string<date-time>

required

updated_at

string<date-time>

required

deleted_at

string<date-time> | null

required

⌘I

Overview

Responses and conversations

Models and routing

Images and audio

Files and retrieval

Agents

Tools and sandbox

Evals and feedback

Compute

Repositories

Dataset generations

Organizations and access

Usage and budgets

Application utilities

Analytics

Legacy APIs

Additional APIs

Create a connector

Authorizations

Headers

Path Parameters

Body

Response