Quickstart

Create a keyCopy Anchor Link

In Sonecentral, open Metin asistanı (Text assistant) and create a key under API anahtarları (API keys). Only workspace administrators see this section. Tür (Type) offers two choices:

• Server key starts with sk-sone-v1- and belongs in your backend. Never put it in a browser, mobile app bundle or public repository.
• Publishable key starts with pk-sone-v1- and is for your website's chat widget. It works only from your allowed origins.

The key is shown once, when created. Save it immediately as an environment variable:

export SONE_API_KEY="sk-sone-v1-..."

Details: Authentication and keys.

Find your assistant's IDCopy Anchor Link

curl https://pb.sonecentral.com/api/v1/models \
  -H "Authorization: Bearer $SONE_API_KEY"

Use the listed id as model. If the key allows only one assistant, "default" is sufficient.

Send the first messageCopy Anchor Link

curl https://pb.sonecentral.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      { "role": "user", "content": "Can I book an appointment tomorrow afternoon?" }
    ]
  }'

Install with npm i openai, pip install openai or npm i ai @ai-sdk/openai. Examples were tested with openai 7 (Node), openai 2 (Python), ai 7 and @ai-sdk/openai 4.

Continue the conversationCopy Anchor Link

The response includes choices[0].message.sone.conversation_id. Send it back in metadata on the next request so the assistant remembers earlier messages. When sending only the new message, add an Idempotency-Key to each message: retrying after a network failure with the same key prevents duplicate storage.

// OpenAI types omit `sone`; see the Chat Completions page for its type.
const { sone } = completion.choices[0].message as unknown as {
  sone: { conversation_id: string };
};

await client.chat.completions.create(
  {
    model: 'default',
    metadata: { conversation_id: sone.conversation_id },
    messages: [{ role: 'user', content: 'Is four oclock available?' }],
  },
  { headers: { 'Idempotency-Key': crypto.randomUUID() } },
);

Other continuation methods, retries and browser persistence: Conversation continuity.