Integrating Chatbot UI with Fikra API

Prerequisites

• A Fikra API account with a valid API key (fk_live_...).
• Node.js (v18+) and npm installed.
• Chatbot UI installed and running locally.
• Access to the Fikra dashboard to manage API keys and token credits.

Environment Variable Setup

Chatbot UI supports custom OpenAI-compatible endpoints. You will need to configure the base URL and API key. Since Chatbot UI typically uses environment variables or a .env file for configuration, add the following:

# .env
FIKRA_API_KEY=fk_live_your_key_here
FIKRA_BASE_URL=https://api.fikraapi.co.ke/v1

In the Chatbot UI configuration (usually config.json or via the UI settings for custom models), set the provider to openai (or custom if available) and specify: - Base URL: https://api.fikraapi.co.ke/v1 - API Key: Your Fikra API key - Model: fikra-flash

Python Example

If you are building a custom backend or testing the connection before integrating with Chatbot UI, here is a Python example using the openai library, which is compatible with Fikra's interface:

import os
from openai import OpenAI

# Initialize the client with Fikra's base URL and API key
client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

# Make a chat completion request
response = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, Fikra!"}
    ]
)

print(response.choices[0].message.content)

Streaming Guidance

Fikra supports streaming via Server-Sent Events (SSE) when stream: true is set. In Chatbot UI, ensure that streaming is enabled in the model configuration. For custom implementations, use the stream parameter:

stream = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "user", "content": "Explain quantum computing simply."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Common Errors

• 400 Bad Request: Malformed JSON, missing required fields, or invalid model alias. Verify that model is one of the listed Fikra aliases (e.g., fikra-flash).
• 401 Unauthorized: Invalid or missing API key. Ensure the Authorization: Bearer fk_live_... header is correctly set.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up via the Fikra dashboard using M-Pesa or cards.
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM. Implement exponential backoff.
• 503 Service Unavailable: Temporary server issue. Retry with backoff. Check the Fikra dashboard for status updates.

Production Checklist

• [ ] Use environment variables for API keys; never hardcode them.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard to avoid 402 errors.
• [ ] Test streaming behavior in your UI to ensure SSE chunks are handled correctly.
• [ ] Verify that the model alias (fikra-flash) is available in your account's model registry.
• [ ] Ensure your backend supports HTTPS and proper CORS if serving the UI from a different origin.