> This page is for version v2026.01.16-dev.
> For other versions, use one of these documentation indexes:
> - latest (default): https://docs.machanirobotics.dev/latest/llms.txt
> - v2026.01.16-dev: https://docs.machanirobotics.dev/v-2026-01-16-dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.machanirobotics.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.machanirobotics.dev/_mcp/server.

# Microphone Control

POST https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl
Content-Type: application/json

MicrophoneControl controls the state of the microphone based on the incoming
 request.

 When a MicrophoneControl is received, the service will either
 activate or deactivate the microphone. The response
 (MicrophoneControlRequest) includes the updated microphone state, any
 relevant audio data, and transcribed text if available.

 HTTP Mapping:
   POST "/v1/conversation/audio/microphone:microphoneControl"
   The entire request body is forwarded to the service.

Reference: https://docs.machanirobotics.dev/v-2026-01-16-dev/2026-01-16-dev/latest/audio-service/microphonecontrol

## Request

### Body (application/json)

This endpoint expects a MicrophoneControlRequest.

- `toggle` (boolean, required) — Desired state for the microphone. Set to true to activate the microphone; false to deactivate.
- `audio` (Audio, required) — Audio data and metadata associated with the control request. Provides additional context if needed during processing.

## Response

### 200

OK

- `audioState` (integer, optional) — The current state of the microphone after processing the control request. Indicates whether the microphone is active (on) or inactive (off).
- `audio` (Audio, optional) — Audio data and associated metadata returned in the response.

## Errors

### 400 Bad Request Error

Bad Request

- `code` (integer, optional) — The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
- `message` (string, optional) — A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
- `details` (list of GoogleProtobufAny, optional) — A list of messages that carry the error details. There is a common set of message types for APIs to use.

## Types

### Audio

Audio represents an audio resource within the conversation processing system. It encapsulates raw audio data along with its metadata and parameters required for tasks such as transcription, voice activity detection, and further audio analysis.

- `service` (integer, required) — The audio processing service to be used for handling this audio. Examples include Whisper.CPP or Google Speech-to-Text.
- `languageTag` (InferenceLanguage, required) — InferenceLanguage represents the language of the audio data. It specifies the language code (e.g., "en-US") for the audio content. includes which service to use as well.
- `name` (string, optional) — Unique identifier for the audio resource. This field uniquely distinguishes an audio instance within the system.
- `audioData` (string, optional) — Raw audio data represented as a sequence of bytes. Audio may be provided in multiple chunks if needed.
- `uploadPath` (string, optional) — Optional upload path for storing the audio file. This may specify a cloud storage path or other destination for the processed audio.
- `livePipelineFilePath` (string, optional) — File path for the live audio processing pipeline. This is the location where the live audio file (default: /tmp/transcribe.wav) is stored during processing.
- `vadThreshold` (double, optional) — Voice Activity Detection (VAD) threshold. Specifies the minimum energy level for the microphone to consider input as speech, helping to distinguish speech from background noise.
- `sampleRate` (integer, optional) — The sample rate of the audio, expressed in Hertz (Hz). For example, a value of 16000 indicates the audio was sampled 16,000 times per second.
- `wordwiseTimestamps` (list of AudioWordwiseTimestamp, optional) — Optional word-level timestamps for the audio stream. Provides detailed timing (start, end) and confidence information for each recognized word. If multiple words are recognized, consider making this field repeated.

### GoogleProtobufAny

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

- `@type` (string, optional) — The type of the serialized message.

### InferenceLanguage

InferenceLanguage is the language code for the robot's conversation.

- `countryTag` (integer, required) — The country code for the robot's conversation.
- `languageTag` (integer, required) — The language code for the robot's conversation.
- `inputAudio` (string, optional) — The audio input for the robot's conversation.
- `inputText` (string, optional) — The text input for the robot's conversation.
- `inputSpeech` (string, optional) — The speech input for the robot's conversation.
- `inputNone` (boolean, optional) — The none input for the robot's conversation.
- `outputAudio` (string, optional) — The audio output for the robot's conversation.
- `outputText` (string, optional) — The text output for the robot's conversation.
- `outputSpeech` (string, optional) — The speech output for the robot's conversation.
- `outputNone` (boolean, optional) — The none output for the robot's conversation.

### AudioWordwiseTimestamp

AudioWordWiseTimeStamp represents the timing and confidence details for each recognized word in an audio stream.

- `word` (string, optional) — The recognized word from the audio.
- `start` (string, optional) — The start time (in seconds) when the word begins in the audio stream.
- `end` (string, optional) — The end time (in seconds) when the word finishes in the audio stream.
- `probability` (double, optional) — The confidence probability of the recognized word. A value between 0.0 and 1.0, where 1.0 indicates highest confidence.

## Examples

**Request**

```json
{
  "toggle": true,
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033
    }
  }
}
```

**Response**

```json
{
  "audioState": 1,
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033,
      "inputAudio": "microphone_input_stream",
      "inputText": "Activate microphone",
      "inputSpeech": "Please turn on the microphone",
      "inputNone": false,
      "outputAudio": "response_audio_stream",
      "outputText": "Microphone activated",
      "outputSpeech": "The microphone is now on",
      "outputNone": false
    },
    "name": "session_audio_202406",
    "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "uploadPath": "s3://machani-audio-uploads/session_audio_202406.wav",
    "livePipelineFilePath": "/tmp/transcribe.wav",
    "vadThreshold": 0.5,
    "sampleRate": 16000,
    "wordwiseTimestamps": [
      {
        "word": "Activate",
        "start": "0.00s",
        "end": "0.45s",
        "probability": 0.98
      },
      {
        "word": "microphone",
        "start": "0.46s",
        "end": "1.10s",
        "probability": 0.95
      }
    ]
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl"

payload = {
    "toggle": True,
    "audio": {
        "service": 2,
        "languageTag": {
            "countryTag": 840,
            "languageTag": 1033
        }
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"toggle":true,"audio":{"service":2,"languageTag":{"countryTag":840,"languageTag":1033}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl"

	payload := strings.NewReader("{\n  \"toggle\": true,\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"toggle\": true,\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl")
  .header("Content-Type", "application/json")
  .body("{\n  \"toggle\": true,\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl', [
  'body' => '{
  "toggle": true,
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033
    }
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"toggle\": true,\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "toggle": true,
  "audio": [
    "service": 2,
    "languageTag": [
      "countryTag": 840,
      "languageTag": 1033
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.machanirobotics.com/v1/conversation/audio/microphone:microphoneControl")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```