Skip to content

Chapter 4 — APIs

Integration APIs

The five HTTP exchanges that carry a call from session creation through user input, chatbot response and message retrieval.

1. Conversation initiation

When a call is connected to the SIP Connector, it requests a conversation session from the Conversation Controller.

POST /api/voiceconnector/create_conversation application/json

  • sender_id — String. Phone number of the caller initiating the conversation.
  • session_id — String. Identifier of the BlockFlow project session configured in the SIP Connector.
{
"sender_id": "<caller phone number>",
"session_id": "<BlockFlow project session ID set in SIP Connector>"
}

The request initialises a new VoiceBot conversation session. The system returns the audio path of the predefined welcome message configured in the system settings.

2. Capturing user input

The SIP Connector records the user's speech and forwards the audio file to the Conversation Monitor.

POST /api/voiceconnector/exchange application/json

{
"sender_id": "<phone_number>",
"conversation_id": "<conversation_id>",
"audio_path": "<recorded audio file>"
}

Processing workflow

  1. Speech transcription — the recorded audio is converted to text by the STT module.
  2. Chatbot processing — the transcript is forwarded for intent analysis and response generation.
  3. Error handling — on failure, an error is generated and the user is transferred to a live agent.
  4. Response synchronisation — on success, a semaphore is created to wait for the chatbot response.
  5. Response delivery — once the chatbot responds, the semaphore is released and the message is delivered.

Exceptions

Exception Code Description
ConversationNotFoundException 404 The conversation entity with the given sessionId is not found in the repository.
TokenNotValid 401 The provided token does not match the expected token stored in the session settings.
LateResponseException 408 A message is received for a finished conversation and the VDN matches the REDIRECT_VDN property — a business-specific late reply case.
ConversationEndedException 400 The conversation status is not ACTIVE and it is not eligible for VDN-based redirection.
JsonProcessingException 500 Jackson exception occurring during serialisation or deserialisation of messages.
IllegalArgumentException 400 Raised on parsing failures or an invalid enum or value.

3. Receiving a response from BlockFlow

Two configurable tokens in the project settings secure the integration in both directions. One token accompanies every request the platform sends to the chatbot, so the chatbot can verify the caller is legitimate. A second token accompanies every message the chatbot posts back to /api/message/receive , so the platform can authenticate the sender. These mutual checks maintain a trusted channel between the Conversation Controller and BlockFlow.

POST /api/message/receive application/json

{
"message": "<text response or control message>",
"session_id": "<session ID provided to the chatbot>",
"last_message": 0,
"vdn": null
}

Behaviour by message type

  • Text message — converted to speech and played to the user.
  • Control message — modifies conversation parameters such as recording duration, silence detection or submit state.
  • Submit / last message — the semaphore is released and the response is delivered.
  • Intermediate message — the system waits for additional messages before continuing.

4. Retrieving additional messages

If a received message is not marked as the last one, the SIP Connector requests the remaining chatbot responses.

POST /api/voiceconnector/exchange_resume/{conversation_id}

Content type is application/x-www-form-urlencoded . The system checks whether the final message has arrived: if it has, the message is delivered immediately; if not, the semaphore is acquired and the system waits until it becomes available.

5. Sending user messages to the chatbot

POST https://<chatbot-host>/receive application/json

{
"sender_id": "<phone number>",
"message": "<transcribed customer message>",
"organization_id": "<organization id>",
"session_id": "<session id>"
}

Each request includes pre-generated authentication tokens to secure communication with the chatbot service.