Python (SDK)

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,
            ],
        },
        "drop_pending_updates": True,
    })

    # Handle response
    print(res)

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,
        ],
      },
      dropPendingUpdates: true,
    },
  });

  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

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
    ]
  },
  "drop_pending_updates": true
}
'

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]},
    drop_pending_updates: true
  })
};

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
        ]
    ],
    'drop_pending_updates' => true
  ]),
  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  \"drop_pending_updates\": true\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  \"drop_pending_updates\": true\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  \"drop_pending_updates\": true\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

Python (SDK)

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,
            ],
        },
        "drop_pending_updates": True,
    })

    # Handle response
    print(res)

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,
        ],
      },
      dropPendingUpdates: true,
    },
  });

  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

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
    ]
  },
  "drop_pending_updates": true
}
'

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]},
    drop_pending_updates: true
  })
};

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
        ]
    ],
    'drop_pending_updates' => true
  ]),
  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  \"drop_pending_updates\": true\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  \"drop_pending_updates\": true\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  \"drop_pending_updates\": true\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

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

drop_pending_updates

enum<boolean>

default:true

Always true: Telegram discards updates queued before this tenancy's webhook is registered.

Available options:

true

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 API

Agents API

Platform APIs

Administration

Sandbox API

Compute API

Repositories API

Deprecated

Other

Create a connector

Authorizations

Headers

Path Parameters

Body

Response