Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_conversation_add_outbound_message

Add an external outbound call to a GoHighLevel conversation by posting call details, status, and either conversationId or contactId to record it in the correct thread.

Instructions

Add an external outbound call Post the necessary fields for the API to add a new outbound call. Endpoint: POST /conversations/messages/outbound (Version header: v3; source: v3/conversations-v3.json) OAuth scopes: conversations/message.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "ghl_conversation_add_outbound_message"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesOne of conversationId or contactId must be provided. When conversationId is omitted, the conversation is resolved or created from contactId.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv2.1.0
    • changedInput schema / properties / body / description
      Previous value: -"Request body (schema carried verbatim from the official OpenAPI spec)."New value: +"One of conversationId or contactId must be provided. When conversationId is omitted, the conversation is resolved or created from contactId."
    • removedInput schema / properties / body / properties / attachments / example
      Removed value: -[
      -  "https://example.com/files/recording.mp3"
      -]
    • changedInput schema / properties / body / properties / call / allOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "from": {
      -        "description": "Phone number of the dialer",
      -        "example": "+15037081210",
      -        "type": "string"
      -      },
      -      "status": {
      -        "description": "Call status",
      -        "enum": [
      -          "pending",
      -          "completed",
      -          "answered",
      -          "busy",
      -          "no-answer",
      -          "failed",
      -          "canceled",
      -          "voicemail"
      -        ],
      -        "example": "completed",
      -        "type": "string"
      -      },
      -      "to": {
      -        "description": "Phone number of the receiver",
      -        "example": "+15037081210",
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "from": {
      +        "description": "Phone number of the dialer",
      +        "example": "+15037081210",
      +        "type": "string"
      +      },
      +      "status": {
      +        "description": "Call status",
      +        "enum": [
      +          "pending",
      +          "completed",
      +          "answered",
      +          "busy",
      +          "no-answer",
      +          "failed",
      +          "canceled",
      +          "voicemail"
      +        ],
      +        "example": "completed",
      +        "type": "string"
      +      },
      +      "to": {
      +        "description": "Phone number of the receiver",
      +        "example": "+15037081210",
      +        "type": "string"
      +      }
      +    },
      +    "title": "CallDataDTO",
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / body / properties / call / example
      Removed value: -{
      -  "from": "+15037081211",
      -  "status": "completed",
      -  "to": "+15037081210"
      -}
    • addedInput schema / properties / body / properties / contactId
      Added value: +{
      +  "description": "Contact Id. When provided without conversationId, the conversation is resolved or created from this contact.",
      +  "example": "ve9EPM428h8vShlRW1KT",
      +  "type": "string"
      +}
    • changedInput schema / properties / body / properties / conversationId / description
      Previous value: -"Conversation Id"New value: +"Conversation Id. Provide either conversationId or contactId."
    • removedInput schema / properties / body / properties / date / example
      Removed value: -"2024-03-27T18:13:49.000Z"
    • changedInput schema / properties / body / required
      Previous value: -[
      -  "type",
      -  "conversationId",
      -  "conversationProviderId"
      -]New value: +[
      +  "type",
      +  "conversationProviderId"
      +]
    • addedInput schema / properties / body / title
      Added value: +"ProcessOutboundMessageBodyDto"
  2. First observedv2.0.0

TDQS

B3.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by naming the required OAuth scope (conversations/message.write) and API version header, which are things the agent must know before calling. It stops short of saying whether a conversation is created as a side effect or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short and front-loaded: the action is in the first sentence. The endpoint/version/source line is mildly noisy metadata but useful for debugging and costs a single sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation with no output schema, the description should at least hint at what comes back (e.g., created message/call id). It covers auth scope and endpoint but omits the return shape and any side effects, leaving gaps that the schema alone does not fill.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single nested body parameter and its fields are fully documented in the schema, including the conversationId-vs-contactId rule. The description only says 'Post the necessary fields' and adds no semantics beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (“Add an external outbound call”) and pins it to the exact endpoint POST /conversations/messages/outbound, so an agent knows this creates an outbound call record. It does not distinguish itself from nearby siblings such as ghl_conversation_add_inbound_message or ghl_conversation_send_message, and the name/description mismatch ('message' vs 'call') is only resolved by the schema's type enum of ['Call'].

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no statement of what this is for versus other message-creation tools, and no prerequisites beyond the OAuth scope line. It is purely a restatement of the add operation plus endpoint metadata.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools