Neuron Conversations API
List, monitor, and manage conversations
List, monitor, and manage conversations
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/neuron-ng:neuron-ng-conversations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Neuron Conversations API
version: 1.0.0
description: 'API reference for Neuron — the AI-powered WhatsApp chatbot platform.
Neuron lets you build intelligent chatbots with tool integrations, knowledge bases, and human-in-the-loop monitoring.
## Authentication
Most endpoints require a JWT bearer token obtained from `POST /auth/login`.
Bot API endpoints use API keys prefixed with `nrn_`.
The **Social API** (`/social`) is organization-scoped — authenticate with an **account token** (`nrn_acc_`, from Dashboard → Settings → Account Tokens). Bot API keys are also accepted for backward compatibility but are legacy for this API.
## Response Format
All responses follow the envelope: `{ success: boolean, data?: any, error?: { message, code } }`'
servers:
- url: /api/v1
description: API v1
tags:
- name: Conversations
description: List, monitor, and manage conversations
paths:
/conversations/bot/{botId}:
get:
tags:
- Conversations
summary: List conversations for bot
security:
- BearerAuth: []
parameters:
- name: botId
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: status
in: query
schema:
type: string
description: Filter by status
- name: page
in: query
schema:
type: string
description: Page number
- name: limit
in: query
schema:
type: string
description: Items per page
responses:
'200':
description: Paginated list
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Conversation'
total:
type: integer
page:
type: integer
limit:
type: integer
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getConversationsBotByBotId
x-operation-id-source: derived
/conversations/{id}:
get:
tags:
- Conversations
summary: Get conversation details
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Conversation'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getConversationsById
x-operation-id-source: derived
/conversations/{id}/messages:
get:
tags:
- Conversations
summary: Get messages in conversation
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
- name: page
in: query
schema:
type: string
description: Page number
- name: limit
in: query
schema:
type: string
description: Items per page
responses:
'200':
description: Paginated list
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Message'
total:
type: integer
page:
type: integer
limit:
type: integer
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: getConversationsByIdMessages
x-operation-id-source: derived
/conversations/{id}/takeover:
post:
tags:
- Conversations
summary: Take over conversation (human agent)
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postConversationsByIdTakeover
x-operation-id-source: derived
/conversations/{id}/release:
post:
tags:
- Conversations
summary: Release conversation back to bot
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postConversationsByIdRelease
x-operation-id-source: derived
/conversations/{id}/send:
post:
tags:
- Conversations
summary: Send message as agent
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
requestBody:
content:
application/json:
schema:
type: object
required:
- content
properties:
content:
type: string
required: true
responses:
'201':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Message'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postConversationsByIdSend
x-operation-id-source: derived
/conversations/{id}/close:
post:
tags:
- Conversations
summary: Close conversation
security:
- BearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ''
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postConversationsByIdClose
x-operation-id-source: derived
/conversations/compose-story:
post:
tags:
- Conversations
summary: Post a WhatsApp Status / Story
security:
- BearerAuth: []
description: Posts a Status visible to the account's synced contacts for 24h. Direct (Baileys) sessions only; channelId auto-resolves when omitted. Recipients are resolved automatically.
requestBody:
content:
application/json:
schema:
type: object
properties:
channelId:
type: string
format: uuid
description: Direct (Baileys) session to post from. Omit to auto-resolve to the default / first connected session.
text:
type: string
description: Status text, or caption for a media status.
messageType:
type: string
enum:
- text
- image
- video
- audio
default: text
mediaUrl:
type: string
format: uri
description: Required for image, video and audio statuses.
backgroundColor:
type: string
example: '#315575'
description: Text-status background colour (hex). Ignored for media.
font:
type: integer
minimum: 0
maximum: 9
description: Text-status font index.
statusJidList:
type: array
items:
type: string
description: Optional. Target a subset of contacts. Omit to reach all synced contacts (minus opt-outs).
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
message:
type: string
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
operationId: postConversationsComposeStory
x-operation-id-source: derived
components:
schemas:
Conversation:
type: object
properties:
id:
type: string
format: uuid
botId:
type: string
format: uuid
status:
type: string
enum:
- active
- escalated
- closed
- archived
contactName:
type: string
contactPhone:
type: string
createdAt:
type: string
format: date-time
Message:
type: object
properties:
id:
type: string
format: uuid
conversationId:
type: string
format: uuid
role:
type: string
enum:
- user
- assistant
- agent
- system
content:
type: string
createdAt:
type: string
format: date-time
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
message:
type: string
code:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token from POST /auth/login
ApiKeyAuth:
type: http
scheme: bearer
description: Bot API key (nrn_xxx) from bot API keys management
AccountTokenAuth:
type: http
scheme: bearer
description: Account token (nrn_acc_xxx) from Dashboard > Settings > Account Tokens