Five Ways to Integrate with raia
raia is designed to be the intelligence layer that connects to your existing technology stack. There are five distinct integration pathways, each serving a different architectural purpose.
Pathway 1: Expose raia knowledge or an agent to external MCP clients (External → raia)
Direction: A compatible external MCP client queries raia
How it works: Choose a Command knowledge server for scoped document access or CX agent MCP for queries to a configured agent:
- raia Command → MCP Servers: creates a server scoped to the knowledge you select. See Command MCP Servers.
- raia CX → agent → Skills → MCP: sets up MCP access for that configured agent. See MCP Server skill.
Endpoint and credentials: Copy the endpoint and credential that your own setup screen generates. Do not build the URL by hand from a pattern; follow the linked guide for the exact steps.
Example use case (hypothetical): A developer's MCP-compatible IDE assistant asks a question about internal API documentation and gets an answer from the scoped raia knowledge. What a client can see or do depends on the client, the server setup and its permissions.
Pathway 2: Connect raia agents to external MCP servers (raia → External)
Direction: Your raia agent uses an external MCP server you are permitted to connect
How it works: Where your setup supports it, an agent can be connected to a compatible external MCP server. Which tools become available, and whether they are discovered, depends on the client and server, the permissions granted and how the connection is configured. Access is not automatic or guaranteed.
Example use case (hypothetical, not tested in these docs): A user asks a support agent for the status of a ticket, and the agent looks it up through a ticketing MCP server that the organization has connected and authorized.
Network reachability: Connecting to a server inside a private network (for example a VPC or on-premises system) is a hypothetical scenario in these docs. It would require approved network connectivity from raia's deployment; a hosted raia agent cannot automatically reach private systems.
Pathway 3: Connect to Workflows (Sync) via Functions
Direction: Agent calls an external API mid-conversation in real-time
How it works: The Functions Skill (covered in Module 5) allows the agent to pause the conversation, call an external HTTP endpoint, wait for the response, and incorporate the result into its reply.
Key characteristic: Synchronous — the agent waits for the response before replying to the user.
Use case: User asks "What's my account balance?" → Agent calls your billing API → Returns the balance in natural language.
Pathway 4: Connect to Workflows (Async) via Webhooks
Direction: Agent pushes data to external systems after an event
How it works: The agent fires data out to an external system when a specific event occurs. It does NOT wait for a response.
Two webhook triggers:
| Event | When It Fires | Ideal For |
|---|---|---|
| onMessageEnd | Every time the agent sends a reply | Real-time dashboards, live syncs |
| onThreadEnd | When a conversation is complete (after ~6 min of inactivity) | Logging full transcripts to CRM, post-conversation automation |
Payload includes: Agent identity (agent_name), thread context (thread_id, channel), user data (user_name, user_email, user_phone), message content, and metadata (timestamps, scoring data).
Pathway 5: Connect TO raia Agents via API (External → raia)
Direction: Your application programmatically starts conversations and sends messages
How it works: In raia CX, open Agents → your agent → Skills. If API is not listed yet, use Add skill and select + on the API card, then select Edit (pencil). Select Create API Key, enter a Name and Expiration date, and select Create key. The full key is shown once — copy it into a private store before Done; afterwards the list shows only a masked preview.
Worked example
The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.
If API is not on the agent yet, open Add skill and select + on the API card.
- Highlight 1: + (add API)
Once added, select Edit (pencil) on the API card. Adding the skill does not create a key.
- Highlight 1: Edit (pencil)
Worked example
The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.
With no keys yet, the list is empty. Select Create API Key.
- Highlight 1: Create API Key
- Highlight 2: No API keys yet
Enter a Name that identifies where the key will be used and choose an Expiration date, then Create key. Choose a lifetime that fits your team’s policy and plan how to replace the key before it expires.
- Highlight 1: Name
- Highlight 2: Expiration date
- Highlight 3: Create key
The full key is shown once with Save your key now - it will never be shown again. Copy it into a private password manager or secret store before you select Done. Never share the key in chat, documentation or screenshots.
- Highlight 1: Save your key now - it will never be shown again.
To stop using a key, select Revoke and reload to confirm the state.
Worked example
The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.
After Done, the list shows only a masked Key preview with Status, Expires and Created. It cannot reveal the full key again; if you lost it, create a new key and revoke the old one.
- Highlight 1: Key preview (masked)
- Highlight 2: Active
- Highlight 3: Revoke
To stop using a key, select Revoke and reopen the list to check Revoked. Update the application’s stored credential if it needs a replacement, and check that a request using the old key is refused. Use the documented API reference for the request and authentication header.
- Highlight 1: Revoked key status
- Highlight 2: Delete (only remaining action)
Key endpoints:
POST /external/conversations— Create a new conversation (requiresconversationUserId; optionaltitleandcontext)POST /external/conversations/{id}/messages— Send a message to an existing conversationGET /external/conversations/{id}— Retrieve conversation details and metadata (no messages)GET /external/conversations/{id}/messages— Retrieve the conversation's saved messages (history)POST /external/conversations/start— Outbound only: starts an email, SMS or voice conversation that contacts a recipient; requires an authorized channel/account. Not for ordinary web chat.
Authentication: Pass Agent-Secret-Key: YOUR_KEY in the header of every request. Other operations can use Organization-Secret-Key — check each operation's schema, and treat any compromised key as urgent regardless of scope.
Full docs: https://api.raia2.com/api/external/docs
Choosing the Right Pattern
| I want to... | Use This Pathway |
|---|---|
| Let developers query my agent from their IDE | MCP Server (Pathway 1) |
| Give my agent access to Jira/GitHub/databases | MCP Client (Pathway 2) |
| Pull live data into a conversation (order status, account info) | Functions (Pathway 3) |
| Push conversation data to my CRM after each chat | Webhooks (Pathway 4) |
| Build a completely custom chat UI or trigger agents from my app | API (Pathway 5) |
Key Distinction: Functions PULL data into the conversation (synchronous, agent waits for response). Webhooks PUSH data out after an event (asynchronous, agent does not wait).