1. DG
Dialgood
  • DG
    • Partner API
    • Call Control
      • Mute an active call
      • Unmute an active call
      • Clear Outbound Call Queue
      • Message Announcement
    • Live Status
      • Get transcript and transcript entries for a campaign
      • Get normalized call status and CDR details for a campaign
    • Voices
      • List available voices with optional filters and pagination
    • Calls
      • Place Outbound Call
      • Get Live Call Transcript
      • Get Call Transcript
      • Get Call Records
      • Get Call Recording
    • Agents
      • Get Agents
  • Schemas
    • Sample Schemas
      • Pet
      • Category
      • Tag
    • outbound body
    • ErrorResponse
    • ProxyControlRequestBody
    • ProxyControlResponse
    • LiveTranscriptEntry
    • LiveTranscriptResponse
    • CdrStatusResponse
    • VoiceLabels
    • Voice
    • VoicesPaginatedResponse
  1. DG

Partner API

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"
}
StatusMeaning
200Request succeeded.
201Resource was created.
400Request body is malformed or missing required fields.
401API key is missing or invalid.
403Partner API access is disabled or the authenticated user does not have write access to the agent.
404The requested agent or version was not found for this user.
500Unexpected server error.

Voices#

The Partner API exposes the same voice catalog and filtering behavior as GET /external/v1/voices.
Optional query parameters:
ParameterTypeDescription
vendorstringVoice provider. Defaults to elevenlabs; supported values are elevenlabs, deepgram, whisper, microsoft, google, and cartesia.
pagenumberPage number. Defaults to 1.
limitnumberVoices per page. Defaults to 10.
genderstringFilter voices by gender.
accentstringFilter voices by accent.
namestringFilter 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:
ParameterTypeDescription
limitnumberMaximum number of agents to return. Defaults to 25.
skipnumberNumber 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:
1.
Normalize the submitted agent and synthesizer configuration.
2.
Create a server-generated version_id and the next version_number.
3.
Store the complete normalized agent snapshot in the version's updates field.
4.
Record the commit message, authenticated actor, user ID, and timestamp.
5.
Update the current MongoDB agent.
6.
Refresh the Redis runtime build cache.
7.
Refresh the DynamoDB runtime projection and synchronize phone-number lookups.
8.
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:
ParameterTypeDescription
fromnumberStart timestamp for the call-log range.
tonumberEnd timestamp for the call-log range.
pagenumberPage number. Defaults to 1.
limitnumberRecords per page. Defaults to 10.
tzstringTimezone used by the CDR lookup. Defaults to Australia/Melbourne.
fromnumberstringFilter by caller number.
tonumberstringFilter by destination number.
statusstringFilter by call status.
directionstringFilter by call direction.
campaignstringFilter by campaign ID.
conversationidstringFilter by conversation ID.
hidewebcallsbooleanSet 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.
Register with PUT and a public HTTPS URL:
{
  "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:
ParameterTypeDescription
limitnumberMaximum number of versions to return. Defaults to 25.
skipnumberNumber 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#

1.
Store the Dialgood API key securely in the partner backend.
2.
Call GET /agents to map Dialgood agentId values into the partner dashboard.
3.
Read GET /agents/{agentId} before editing so the partner starts from the current configuration.
4.
Create an agent with POST /agents if needed.
5.
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.
6.
Never round-trip masked credential entries through a full agent update. Use the credential endpoint when secrets change.
7.
Use focused endpoints only when the partner UI is editing one supported area, such as credentials or settings.
8.
Fetch GET /agents/{agentId}/versions?limit=1 to confirm that the publish created a managed version.
9.
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.
Modified at 2026-09-14 01:44:15
Next
Mute an active call
Built with