Dialgood Partner Agent API

Use the Partner Agent API to manage Dialgood agents from a partner dashboard. Partner requests act on behalf of the Dialgood user associated with the supplied API key, and agent creates and updates follow the same save/version behavior as the Dialgood dashboard.

The main write path is the version-managed agent update endpoint: PUT /agents/{agentId} for complete agent publishes and PATCH /agents/{agentId} for partial top-level amendments. Both methods follow the same save/version behavior as the Dialgood dashboard. Focused endpoints such as settings and credentials are convenience wrappers over the same agent ownership and persistence model.

Base URL

https://api.dialgood.com/partner/v1

All paths in this document are relative to that base URL.

Access

Partner API access must be enabled for the Dialgood user before requests will succeed. Contact Dialgood if an API key returns 403.

Authentication

Send the Dialgood user API key in the api_token header.

Query-string authentication is also supported for compatibility, but header authentication is recommended.

Request Format

Request bodies are JSON unless otherwise noted.

Agent reads and writes are scoped to the authenticated Dialgood user.

If an agent does not belong to the authenticated user, the API returns 404.

Complete agent publishes should use dashboard-shaped fields such as agentName, design, settings, metadata, and phoneNumbers.

Include metadata.commit_message or metadata.commitMessage when you want a specific version history label.

PUT and PATCH currently use the same top-level merge behavior. Omitted top-level fields are preserved by both methods.

Nested objects included in the request, such as settings, design, or metadata, replace the stored value for that top-level field. Send the complete intended value of every nested object you include.

Credential values must be managed through the credential endpoints so they are encrypted before persistence.

Do not send masked credential entries returned by a general agent read back through the agent update endpoint.

Errors

Error responses use this shape:

{
  "error": "agent not found"
}

Status	Meaning
`200`	Request succeeded.
`201`	Resource was created.
`400`	Request body is malformed or missing required fields.
`401`	API key is missing or invalid.
`403`	Partner API access is disabled or the authenticated user does not have write access to the agent.
`404`	The requested agent or version was not found for this user.
`500`	Unexpected server error.

Voices

The Partner API exposes the same voice catalog and filtering behavior as GET /external/v1/voices.

Optional query parameters:

Parameter	Type	Description
`vendor`	string	Voice provider. Defaults to `elevenlabs`; supported values are `elevenlabs`, `deepgram`, `whisper`, `microsoft`, `google`, and `cartesia`.
`page`	number	Page number. Defaults to `1`.
`limit`	number	Voices per page. Defaults to `10`.
`gender`	string	Filter voices by gender.
`accent`	string	Filter voices by accent.
`name`	string	Filter voices by a case-insensitive partial name match.

The /voices catalog endpoint currently returns elevenlabs, deepgram, whisper, microsoft, google, and cartesia voices. Agent updates also accept existing Rime voice IDs, but Rime is not currently listed by this endpoint.

Example:

Agents

Agent creates and updates are version-managed like Dialgood dashboard saves. The API confirms ownership, persists the updated agent, creates the corresponding version record, and refreshes the runtime cache used by the agent.

If a Dialgood dashboard edit changes the agent, send the resulting dashboard-shaped agent fields through PATCH /agents/{agentId} or the relevant focused wrapper.

Agent reads include agents owned by the authenticated Dialgood user and agents shared with that user's email address. Shared agents include owner: false, their rights array, and sharing metadata. Owned agents include owner: true.

Shared agents are readable through GET /agents/{agentId}, settings reads, version reads, and call-log reads. Write routes require either ownership or the shared agents right. Credential reads also require agent-control access because they return decrypted values. Shared agents cannot be deleted through the Partner API.

List Agents

Optional query parameters:

Parameter	Type	Description
`limit`	number	Maximum number of agents to return. Defaults to `25`.
`skip`	number	Number of agents to skip. Defaults to `0`.

Example:

Response:

{
  "agents": [
    {
      "agentId": "agent_123",
      "agentName": "Support Agent",
      "userId": "dialgood_user_123",
      "owner": true,
      "settings": {},
      "phoneNumbers": [],
      "metadata": {},
      "updated_at": "2026-05-24T00:00:00.000Z"
    },
    {
      "agentId": "agent_456",
      "agentName": "Shared Sales Agent",
      "userId": "owner_user_456",
      "owner": false,
      "rights": ["view"],
      "settings": {},
      "phoneNumbers": [],
      "metadata": {
        "sharedByEmail": "owner@example.com",
        "sharedByName": "Owner User",
        "sharedAt": "2026-05-24T00:00:00.000Z"
      },
      "updated_at": "2026-05-24T00:00:00.000Z"
    }
  ],
  "totalCount": 2,
  "limit": 25,
  "skip": 0,
  "hasMore": false
}

Create Agent

Example request:

{
  "agentName": "Support Agent",
  "settings": {
    "language": "en"
  },
  "phoneNumbers": [],
  "metadata": {
    "commit_message": "Initial partner setup"
  }
}

Response:

{
  "agent": {
    "agentId": "agent_123",
    "agentName": "Support Agent",
    "userId": "dialgood_user_123",
    "settings": {},
    "phoneNumbers": []
  }
}

Get Agent

Response:

{
  "agent": {
    "agentId": "agent_123",
    "agentName": "Support Agent",
    "userId": "dialgood_user_123",
    "settings": {},
    "phoneNumbers": []
  }
}

Credential values are not returned in the general agent response.

Clone Agent

Creates a new agent owned by the authenticated Dialgood user by copying an existing writable agent. The clone receives a fresh agentId, records a new agent version, and preserves the source agent's configuration. Use request body fields to override editable top-level fields such as agentName or metadata.

The source agent must be owned by the authenticated user or shared with the agents right. Protected fields such as agentId, userId, owner, rights, and timestamps are ignored.

Example request:

{
  "agentName": "Support Agent Copy",
  "metadata": {
    "commit_message": "Partner cloned support agent"
  }
}

Response:

{
  "agent": {
    "agentId": "agent_789",
    "agentName": "Support Agent Copy",
    "userId": "dialgood_user_123",
    "metadata": {
      "clonedFromAgentId": "agent_123"
    }
  }
}

Credential values are not returned in the clone response.

Publish or Update an Agent

Use PUT when publishing the complete editable agent configuration. Use PATCH when changing selected top-level fields. Both methods immediately update the live agent and automatically create a managed version; there is no separate partner draft state.

For a complete publish, send every editable top-level field in its intended final state. Do not include credential values; use the credential endpoint separately.

Credential preservation: settings.credentials is stored inside the settings object, while general agent reads only return masked credential keys. If the agent already has credentials, do not construct a complete settings replacement from the masked general-agent response. Use the focused PATCH /agents/{agentId}/settings endpoint for non-secret settings and the credentials endpoint for secret values. These are separate version-managed operations. The current API does not provide a single atomic publish that replaces all settings, preserves hidden credentials, and creates only one version.

Complete publish example:

{
  "agentName": "Australian Support Agent",
  "design": {
    "greeting_message": "Hello, how can I help?",
    "summaryContext": "Summarise the conversation in five concise points.",
    "knowledgebase": {
      "faqs": [],
      "website": [],
      "text": ""
    },
    "skills": [
      {
        "id": "receptionist",
        "name": "Receptionist",
        "context": "Handle incoming customer enquiries.",
        "tasks": [
          "Understand the caller's request",
          "Answer using the supplied knowledge"
        ],
        "rules": [
          "Keep responses concise",
          "Do not invent information"
        ],
        "objectivesString": "Understand the caller's request\nAnswer using the supplied knowledge",
        "guidelinesString": "Keep responses concise\nDo not invent information",
        "utterances": ["Receptionist"],
        "actions": [],
        "inbound": true,
        "outbound": false,
        "default": true,
        "isActive": true
      }
    ]
  },
  "settings": {
    "language": "en-AU",
    "timezone": "Australia/Melbourne",
    "general": {},
    "voice": {
      "vendor": "microsoft",
      "voice_id": "microsoft-natasha",
      "language": "en-AU",
      "category": "Neural"
    },
    "raw": {
      "synthesizer": {
        "vendor": "microsoft",
        "voice": "microsoft-natasha",
        "language": "en-AU",
        "engine": "neural"
      },
      "recognizer": {
        "vendor": "deepgram",
        "language": "en-AU",
        "model": "nova-2-phonecall",
        "deepgramOptions": {
          "endpointing": 450,
          "utteranceEndMs": 1000,
          "smartFormatting": true,
          "keywords": []
        }
      }
    },
    "telephony": {
      "timezone": "Australia/Melbourne",
      "model": "nova-2-phonecall",
      "pauseDetectionRange": 450,
      "smart_formatting": true
    }
  },
  "phoneNumbers": [
    "+61390000000"
  ],
  "metadata": {
    "commit_message": "Partner publish: updated greeting and Australian voice",
    "partnerRevision": "revision-482"
  }
}

Example request:

Recognized voice names and vendor-prefixed aliases are normalized during publication. For example, microsoft-natasha becomes en-AU-NatashaNeural, and the synthesizer vendor, language, category, and engine are aligned with the Microsoft catalog. Agent updates support elevenlabs, deepgram, whisper, microsoft, google, cartesia, and rime. Unknown custom voice IDs and vendors are preserved.

Response:

{
  "agent": {
    "agentId": "agent_123",
    "agentName": "Australian Support Agent",
    "userId": "dialgood_user_123",
    "settings": {
      "language": "en-AU",
      "voice": {
        "vendor": "microsoft",
        "voice_id": "en-AU-NatashaNeural",
        "language": "en-AU",
        "category": "Neural"
      },
      "raw": {
        "synthesizer": {
          "vendor": "microsoft",
          "voice": "en-AU-NatashaNeural",
          "language": "en-AU",
          "engine": "neural"
        }
      }
    },
    "phoneNumbers": [
      "+61390000000"
    ]
  }
}

The following fields are controlled by Dialgood and ignored on update:

_id
__v
id
agentId
userId
owner
rights
created_at
updated_at

Managed publication behavior

Each successful publish runs the same core persistence path as a Dialgood dashboard save:

Normalize the submitted agent and synthesizer configuration.

Create a server-generated version_id and the next version_number.

Store the complete normalized agent snapshot in the version's updates field.

Record the commit message, authenticated actor, user ID, and timestamp.

Update the current MongoDB agent.

Refresh the Redis runtime build cache.

Refresh the DynamoDB runtime projection and synchronize phone-number lookups.

Remove the oldest version when the account's configured retention limit is reached.

Partners must not call the dashboard-only POST /api/v1/versions endpoint. That endpoint only creates a version record and does not publish the current agent or refresh its runtime projections.

The update response currently does not include the generated version_id or version_number. After publishing, use GET /agents/{agentId}/versions?limit=1 to retrieve the latest version and GET /agents/{agentId}/versions/{versionId} to inspect its complete snapshot.

Version creation, current-agent persistence, cache refresh, and runtime projection are sequential operations rather than one database transaction. Clients should only retry after checking the current agent and latest version to avoid creating an unnecessary additional version.

Delete Agent

Deleting an agent also removes its internal phone-number lookup entries and DynamoDB projection, clears cached agent data, and detaches legacy bot, carrier-connection, and user assignment references. It does not release the customer's phone number or disconnect the carrier integration.

Response:

{
  "status": true
}

Settings

The settings endpoints are convenience wrappers for focused settings edits. They merge the supplied settings keys into the existing settings object and still persist through the version-managed agent update path. For broader dashboard edits, prefer PATCH /agents/{agentId} with the intended agent fields.

Get Settings

Response:

{
  "settings": {
    "language": "en"
  }
}

Update Settings

Example request:

{
  "settings": {
    "language": "en",
    "welcomeMessage": "How can I help?"
  }
}

The endpoint also accepts the settings object directly:

{
  "language": "en",
  "welcomeMessage": "How can I help?"
}

Response:

{
  "settings": {
    "language": "en",
    "welcomeMessage": "How can I help?"
  }
}

You can include metadata.commit_message or metadata.commitMessage alongside settings when you want to label the resulting version.

Credentials

Credential endpoints should only be called from secure server-side partner systems. Do not expose Dialgood API keys or credential values in browser JavaScript.

Get Credentials

Response:

{
  "credentials": [
    {
      "key": "SERVICE_API_KEY",
      "value": "decrypted-secret-value"
    }
  ]
}

Update Credentials

Example request:

{
  "credentials": [
    {
      "key": "SERVICE_API_KEY",
      "value": "new-secret-value"
    }
  ]
}

The endpoint also accepts the credentials array directly:

[
  {
    "key": "SERVICE_API_KEY",
    "value": "new-secret-value"
  }
]

Response:

{
  "status": true
}

Credential updates replace the agent's credential list, encrypt values before persistence, clear the decrypted credential cache for the agent, and create an agent version. You can include metadata.commit_message or metadata.commitMessage alongside credentials when you want to label the resulting version.

Do not include the masked credential entries returned by GET /agents/{agentId} in a complete agent publish. If an agent has stored credentials, use the focused settings endpoint for non-secret settings so omitted credentials remain preserved. A settings update and a credential rotation are separate version-managed operations and each creates its own version.

Call Logs

Call-log reads use the same CDR retrieval path as the Dialgood dashboard and are scoped to the authenticated user's agent.

List Call Logs

Optional query parameters:

Parameter	Type	Description
`from`	number	Start timestamp for the call-log range.
`to`	number	End timestamp for the call-log range.
`page`	number	Page number. Defaults to `1`.
`limit`	number	Records per page. Defaults to `10`.
`tz`	string	Timezone used by the CDR lookup. Defaults to `Australia/Melbourne`.
`fromnumber`	string	Filter by caller number.
`tonumber`	string	Filter by destination number.
`status`	string	Filter by call status.
`direction`	string	Filter by call direction.
`campaign`	string	Filter by campaign ID.
`conversationid`	string	Filter by conversation ID.
`hidewebcalls`	boolean	Set to `true` to hide web calls.

Example:

Response:

{
  "data": [
    {
      "botId": "agent_123",
      "conversationId": "conversation_123",
      "contactId": "contact_123",
      "campaignId": "campaign_123",
      "created_at": "2026-05-24T00:00:00.000Z",
      "data": {
        "from": "+15551234567",
        "to": "+15557654321",
        "direction": "outbound",
        "callStatus": "completed",
        "callDuration": 3
      }
    }
  ],
  "totalPages": 1,
  "totalRecords": 1,
  "currentPage": 1
}

Post-call Webhook

Each partner can register one webhook per writable agent. The registration is separate from agent settings and does not create an agent version.

{
  "url": "https://partner.example/post-call"
}

The signing secret is returned only when the webhook is first created or when rotateSecret: true is supplied. See Agent Post-call Webhooks for the event and signature contract.

Versions

Agent changes made through the Partner API are versioned like dashboard changes. List responses omit the full updates payload for compactness; fetch a specific version when you need the stored update details.

Version identifiers and numbers are managed by Dialgood. Do not supply version_id or version_number in an agent update request.

List Versions

Optional query parameters:

Parameter	Type	Description
`limit`	number	Maximum number of versions to return. Defaults to `25`.
`skip`	number	Number of versions to skip. Defaults to `0`.

Versions are returned newest first. Use limit=1&skip=0 to retrieve the latest managed version after a publish.

Response:

{
  "versions": [
    {
      "version_id": "version_123",
      "version_number": 2,
      "commit_message": "Partner dashboard update",
      "agent_id": "agent_123",
      "metadata": {
        "user": "Partner User",
        "userId": "dialgood_user_123",
        "timestamp": 1779560000000
      }
    }
  ],
  "totalCount": 2,
  "limit": 25,
  "skip": 0,
  "hasMore": false
}

Get Version

Response:

{
  "version": {
    "version_id": "version_123",
    "version_number": 2,
    "commit_message": "Partner dashboard update",
    "agent_id": "agent_123",
    "updates": {},
    "metadata": {
      "user": "Partner User",
      "userId": "dialgood_user_123",
      "timestamp": 1779560000000
    }
  }
}

Recommended Integration Flow

Store the Dialgood API key securely in the partner backend.

Call GET /agents to map Dialgood agentId values into the partner dashboard.

Read GET /agents/{agentId} before editing so the partner starts from the current configuration.

Create an agent with POST /agents if needed.

Publish a complete editable snapshot with PUT /agents/{agentId}, or amend selected top-level fields with PATCH /agents/{agentId}. Include metadata.commit_message for readable version history. If the agent has stored credentials, exclude settings from this operation and update non-secret settings through the focused settings endpoint.

Never round-trip masked credential entries through a full agent update. Use the credential endpoint when secrets change.

Use focused endpoints only when the partner UI is editing one supported area, such as credentials or settings.

Fetch GET /agents/{agentId}/versions?limit=1 to confirm that the publish created a managed version.

Fetch GET /agents/{agentId} to confirm the final normalized live agent state.

10.

Fetch GET /agents/{agentId}/call-logs when the partner dashboard needs call activity.

Security Recommendations

Make Partner API calls from server-side systems only.

Store Dialgood API keys in a secret manager or encrypted configuration store.

Do not log api_token values.

Do not log credential request bodies or decrypted credential responses.

Treat 404 as either a missing agent or an agent that belongs to another Dialgood user.

Rotate Dialgood API keys if a partner system or credential store is compromised.

Partner API

Dialgood Partner Agent API#

Base URL#

Access#

Authentication#

Request Format#

Errors#

Voices#

Agents#

List Agents#

Create Agent#

Get Agent#

Clone Agent#

Publish or Update an Agent#

Managed publication behavior#

Delete Agent#

Settings#

Get Settings#

Update Settings#

Credentials#

Get Credentials#

Update Credentials#

Call Logs#

List Call Logs#

Post-call Webhook#

Versions#

List Versions#

Get Version#

Recommended Integration Flow#

Security Recommendations#

Dialgood Partner Agent API

Base URL

Access

Authentication

Request Format

Errors

Voices

Agents

List Agents

Create Agent

Get Agent

Clone Agent

Publish or Update an Agent

Managed publication behavior

Delete Agent

Settings

Get Settings

Update Settings

Credentials

Get Credentials

Update Credentials

Call Logs

List Call Logs

Post-call Webhook

Versions

List Versions

Get Version

Recommended Integration Flow

Security Recommendations