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: PATCH /agents/{agentId}. Use it for dashboard-equivalent changes to profile fields, settings, and other editable agent data. 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.

Agent amendments should use dashboard-shaped fields such as agentName, settings, metadata, and phoneNumbers.

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

Omitted top-level agent fields are preserved on update. Nested objects that are included in PATCH /agents/{agentId}, such as settings, should be sent as the complete intended object for that field.

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

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 not enabled for this user.
`404`	The requested agent or version was not found for this user.
`500`	Unexpected server error.

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.

Update Agent

Use this endpoint for dashboard-style agent amendments. This is the preferred write path for partner dashboards because it follows the same version-management treatment as Dialgood dashboard saves.

Only send fields the partner dashboard intends to change. If you include a nested object such as settings, send the complete intended value for that object. Do not include credential values in this request; use the credential endpoints instead.

Example request:

{
  "agentName": "Updated Support Agent",
  "settings": {
    "language": "en",
    "welcomeMessage": "How can I help?"
  },
  "phoneNumbers": [
    "+15551234567"
  ],
  "metadata": {
    "commit_message": "Partner dashboard update"
  }
}

Response:

{
  "agent": {
    "agentId": "agent_123",
    "agentName": "Updated Support Agent",
    "userId": "dialgood_user_123",
    "settings": {
      "language": "en",
      "welcomeMessage": "How can I help?"
    },
    "phoneNumbers": [
      "+15551234567"
    ]
  }
}

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

_id
__v
id
agentId
userId
created_at
updated_at

Each successful update records a new agent version. Use GET /agents/{agentId}/versions to list version history and GET /agents/{agentId}/versions/{versionId} to inspect a specific version.

Delete Agent

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.

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
}

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.

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`.

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.

Create an agent with POST /agents if needed.

Update the agent with PATCH /agents/{agentId} for dashboard-style edits and include metadata.commit_message for readable version history.

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

Fetch GET /agents/{agentId}/call-logs to show call activity for the agent.

Fetch GET /agents/{agentId}/versions to confirm that an amendment was recorded.

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

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.

Post-call Webhooks

Register one webhook per writable agent. The registration is stored separately from the agent configuration and is used for calls processed for that agent.

This capability is available on both API surfaces:

Standard API: https://api.dialgood.com/api/v1
Partner API:  https://api.dialgood.com/partner/v1

Use the same resource path with either base URL:

/agents/{agentId}/post-call-webhook

All requests are scoped to the authenticated Dialgood user. The agent must exist and be writable by that user. Partner requests also require Partner API access.

Register or update

The URL must be a publicly reachable HTTPS endpoint. A new registration returns 201; an update returns 200.

{
  "postCallWebhook": {
    "url": "https://partner.example/post-call",
    "hasSecret": true,
    "secret": "whsec_..."
  }
}

The signing secret is returned when the registration is created. Store it securely. To replace it later, send:

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

Get

{
  "postCallWebhook": {
    "url": "https://partner.example/post-call",
    "hasSecret": true
  }
}

If no registration exists, postCallWebhook is null. The secret is never returned by this endpoint.

Delete

{ "status": true }

Delivery

Dialgood sends a JSON POST after a call completes:

{
  "id": "call_123",
  "type": "call.completed",
  "userId": "user_123",
  "agentId": "agent_123",
  "summary": "The customer requested a callback.",
  "status": "completed"
}

Delivery headers:

X-Dialgood-Event-Id: call_123
X-Dialgood-Timestamp: 1778140800
X-Dialgood-Signature: sha256=<hex digest>

Verify X-Dialgood-Signature as the hex HMAC-SHA256 of {timestamp}.{rawBody} using the registration secret. Compare signatures in constant time and reject stale timestamps. Deduplicate deliveries by id.

Network errors, 408, 429, and 5xx responses are retried. Other 4xx responses are not retried. Return any 2xx response promptly after accepting the event.

Partner API

Dialgood Partner Agent API#

Base URL#

Access#

Authentication#

Request Format#

Errors#

Agents#

List Agents#

Create Agent#

Get Agent#

Clone Agent#

Update Agent#

Delete Agent#

Settings#

Get Settings#

Update Settings#

Credentials#

Get Credentials#

Update Credentials#

Call Logs#

List Call Logs#

Versions#

List Versions#

Get Version#

Recommended Integration Flow#

Security Recommendations#

Post-call Webhooks#

Register or update#

Get#

Delete#

Delivery#

Dialgood Partner Agent API

Base URL

Access

Authentication

Request Format

Errors

Agents

List Agents

Create Agent

Get Agent

Clone Agent

Update Agent

Delete Agent

Settings

Get Settings

Update Settings

Credentials

Get Credentials

Update Credentials

Call Logs

List Call Logs

Versions

List Versions

Get Version

Recommended Integration Flow

Security Recommendations

Post-call Webhooks

Register or update

Get

Delete

Delivery