> ## Documentation Index > Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt > Use this file to discover all available pages before exploring further. # 建立或接管聯絡人 > 依據提供的外部身分與嚴格 E.164 號碼，建立、更新或接管組織的標準聯絡人。原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 ## OpenAPI ````yaml /openapi/openapi.zh-Hant.yaml post /contacts openapi: 3.1.0 info: title: Brightalk 公開 API version: '2026-07-16' description: 用於 AI 通話、批次撥號與由儀表板管理之 Automation 執行的私人測試版伺服器對伺服器 REST API。 license: name: Brightalk Private Beta Terms identifier: LicenseRef-Brightalk-Private-Beta servers: - url: https://api.brightalk.ai description: Production security: - bearerAuth: [] tags: - name: Agents description: 可用且由儀表板管理的 AI 語音代理。 - name: Automations description: 由儀表板管理的 Automation 摘要。 - name: Contacts description: 組織的聯絡人與外部身分。 - name: Calls description: 立即執行的非同步 AI 通話及其純量結果。 - name: Batches description: 建立草稿、排程及控制彙總批次撥號。 - name: Automation runs description: 啟動及控制單一聯絡人的 Automation 執行。 paths: /contacts: post: tags: - Contacts summary: 建立或接管聯絡人 description: >- 依據提供的外部身分與嚴格 E.164 號碼，建立、更新或接管組織的標準聯絡人。原始 JSON 主體上限為 1 MiB。每個回應都包含 Brightalk-Version 與 X-Request-Id；受到速率限制的回應還會提供實際套用之配額群組的計數器。 operationId: createContact parameters: - $ref: '#/components/parameters/BrightalkVersion' - $ref: '#/components/parameters/XRequestId' requestBody: required: true description: >- JSON request body. The raw encoded body is limited to 1 MiB and unknown fields are rejected. content: application/json: schema: $ref: '#/components/schemas/CreateContactRequest' responses: '200': description: 已更新或接管既有聯絡人。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Contact' '201': description: 已建立聯絡人。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Contact' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestTooLarge' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' x-codeSamples: - lang: curl label: cURL source: |- curl --request POST 'https://api.brightalk.ai/contacts' \ --header "Authorization: Bearer $BRIGHTALK_API_KEY" \ --header "Brightalk-Version: 2026-07-16" \ --header "Content-Type: application/json" \ --data '{"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}' - lang: javascript label: JavaScript source: |- const response = await fetch("https://api.brightalk.ai/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`, "Brightalk-Version": "2026-07-16", "Content-Type": "application/json", }, body: JSON.stringify({"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}), }); console.log(response.status, await response.json()); - lang: python label: Python source: |- import os import requests response = requests.request( "POST", "https://api.brightalk.ai/contacts", headers={ "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}", "Brightalk-Version": "2026-07-16", "Content-Type": "application/json", }, json={"external_id":"customer-8421","name":"Example Customer","phone_number":"+12025550123"}, ) print(response.status_code, response.json()) components: parameters: BrightalkVersion: name: Brightalk-Version in: header required: false description: 選擇以日期為基礎的 API 版本。省略時會使用組織鎖定的私人測試版預設值。 schema: type: string const: '2026-07-16' default: '2026-07-16' XRequestId: name: X-Request-Id in: header required: false description: 由呼叫端產生且符合 [A-Za-z0-9._:-]{1,64} 的關聯值。無效值會被取代。 schema: type: string pattern: ^[A-Za-z0-9._:-]{1,64}$ maxLength: 64 schemas: CreateContactRequest: type: object additionalProperties: false properties: external_id: type: string pattern: ^\s*\S(?:[\s\S]{0,253}\S)?\s*$ description: 會移除前後空白；剩餘值必須包含 1–255 個字元。 example: customer-8421 source: type: string pattern: ^[a-z][a-z0-9_-]{0,63}$ default: public_api description: 允許清單中的身分命名空間。省略時使用 public_api。 example: public_api name: type: string pattern: ^\s*\S(?:[\s\S]{0,253}\S)?\s*$ description: 會移除前後空白；剩餘值必須包含 1–255 個字元。 example: Example Customer phone_number: type: string pattern: ^\+[1-9]\d{7,14}$ description: 嚴格的 E.164 電話號碼。 example: '+12025550123' email: type: - string - 'null' format: email maxLength: 320 example: customer@example.com company: type: - string - 'null' pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$ description: 會移除前後空白；剩餘值最多可包含 255 個字元。 example: Example Co. role: type: - string - 'null' pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$ description: 會移除前後空白；剩餘值最多可包含 255 個字元。 example: Operations Manager city: type: - string - 'null' pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$ description: 會移除前後空白；剩餘值最多可包含 255 個字元。 example: Taipei country: type: - string - 'null' pattern: ^\s*(?:\S(?:[\s\S]{0,253}\S)?)?\s*$ description: 會移除前後空白；剩餘值最多可包含 255 個字元。 example: TW required: - external_id - name - phone_number Contact: type: object additionalProperties: false properties: id: type: string minLength: 1 maxLength: 255 description: 不透明的資源識別碼。 example: con_demo_001 external_id: type: - string - 'null' description: 由呼叫端管理的外部身分。 example: customer-8421 source: type: - string - 'null' description: 外部身分命名空間。 example: public_api name: type: string example: Example Customer phone_number: type: string pattern: ^\+[1-9]\d{7,14}$ example: '+12025550123' email: type: - string - 'null' description: 聯絡人的電子郵件地址。 example: customer@example.com company: type: - string - 'null' description: 聯絡人的公司。 example: Example Co. role: type: - string - 'null' description: 聯絡人的職務。 example: Operations Manager city: type: - string - 'null' description: 聯絡人的城市。 example: Taipei country: type: - string - 'null' description: 聯絡人的國家或地區。 example: TW created_at: type: string format: date-time description: 聯絡人的建立時間。 example: '2026-07-20T01:00:00Z' updated_at: type: string format: date-time description: 聯絡人上次更新的時間。 example: '2026-07-20T01:00:00Z' required: - id - external_id - source - name - phone_number - email - company - role - city - country - created_at - updated_at ErrorEnvelope: type: object additionalProperties: false properties: error: $ref: '#/components/schemas/Error' required: - error Error: type: object additionalProperties: false properties: code: type: string enum: - authentication_required - invalid_api_key - api_key_expired - organization_not_enabled - insufficient_scope - unsupported_version - validation_error - invalid_json - resource_not_found - resource_state_conflict - method_not_allowed - request_too_large - unsupported_destination - contact_identity_conflict - idempotency_key_required - idempotency_conflict - idempotency_in_progress - duplicate_active_run - rate_limit_exceeded - internal_error example: validation_error message: type: string example: The request could not be validated. request_id: type: string pattern: ^[A-Za-z0-9._:-]{1,64}$ example: req_demo_001 details: $ref: '#/components/schemas/ErrorDetails' required: - code - message - request_id ErrorDetails: type: object additionalProperties: false properties: fields: type: array maxItems: 50 items: $ref: '#/components/schemas/ErrorField' truncated: type: boolean const: true supported_versions: type: array items: type: string pattern: ^\d{4}-\d{2}-\d{2}$ existing_run_id: type: string minLength: 1 maxLength: 255 description: 不透明的資源識別碼。 example: run_demo_001 ErrorField: type: object additionalProperties: false properties: path: type: string example: recipient.phone_number code: type: string example: invalid_e164 required: - path - code headers: Brightalk-Version: description: The date-based version applied to the request. required: true schema: type: string const: '2026-07-16' X-Request-Id: description: The accepted caller correlation value or a server-generated replacement. required: true schema: type: string pattern: ^[A-Za-z0-9._:-]{1,64}$ RateLimit-Limit: description: The effective request allowance for the selected bucket. schema: type: integer minimum: 1 RateLimit-Remaining: description: The nonnegative number of requests remaining in the selected bucket. schema: type: integer minimum: 0 RateLimit-Reset: description: >- A nonnegative integer number of delta-seconds from response generation until the effective bucket resets; never an epoch timestamp. schema: type: integer minimum: 0 Allow: description: A comma-separated list of methods allowed on the known path. schema: type: string example: GET, POST Retry-After: description: >- A nonnegative integer number of delta-seconds to wait before retrying; never an epoch timestamp. schema: type: integer minimum: 0 responses: BadRequest: description: 版本、請求、查詢或與狀態無關的目的地驗證失敗。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: validationError: value: error: code: validation_error message: The request could not be validated. request_id: req_demo_001 details: fields: - path: recipient.phone_number code: invalid_e164 unsupportedVersion: value: error: code: unsupported_version message: The requested API version is not supported. request_id: req_demo_001 details: supported_versions: - '2026-07-16' unsupportedDestination: value: error: code: unsupported_destination message: The destination is not supported. request_id: req_demo_001 Unauthorized: description: 驗證失敗。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: missingBearer: value: error: code: authentication_required message: Authentication is required. request_id: req_demo_001 malformedBearer: value: error: code: authentication_required message: Authentication is required. request_id: req_demo_001 unknownOrRevokedCredential: value: error: code: invalid_api_key message: The API key is invalid. request_id: req_demo_001 expiredCredential: value: error: code: api_key_expired message: The API key has expired. request_id: req_demo_001 Forbidden: description: 組織尚未啟用，或憑證缺少必要的權限範圍。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: organizationNotEnabled: value: error: code: organization_not_enabled message: The organization is not enabled for the Public API. request_id: req_demo_001 insufficientScope: value: error: code: insufficient_scope message: The API key does not have the required scope. request_id: req_demo_001 MethodNotAllowed: description: 路徑已知，但不允許使用此方法。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' Allow: $ref: '#/components/headers/Allow' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: methodNotAllowed: value: error: code: method_not_allowed message: The method is not allowed for this resource. request_id: req_demo_001 Conflict: description: 資源狀態、身分或冪等性宣告與請求衝突。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: stateConflict: value: error: code: resource_state_conflict message: The resource is not in a compatible state. request_id: req_demo_001 identityConflict: value: error: code: contact_identity_conflict message: The contact identity conflicts with an existing contact. request_id: req_demo_001 idempotencyConflict: value: error: code: idempotency_conflict message: >- The idempotency key was already used for a different request. request_id: req_demo_001 idempotencyInProgress: value: error: code: idempotency_in_progress message: A request with this idempotency key is still in progress. request_id: req_demo_001 duplicateActiveRun: value: error: code: duplicate_active_run message: An active run already exists for this contact. request_id: req_demo_001 details: existing_run_id: run_demo_001 RequestTooLarge: description: 原始 JSON 請求主體超過 1 MiB。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: requestTooLarge: value: error: code: request_too_large message: The request body is too large. request_id: req_demo_001 TooManyRequests: description: 所選的請求配額群組已用盡。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rateLimitExceeded: value: error: code: rate_limit_exceeded message: The rate limit has been exceeded. request_id: req_demo_001 InternalError: description: 無法安全完成請求。 headers: Brightalk-Version: $ref: '#/components/headers/Brightalk-Version' X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: internalError: value: error: code: internal_error message: An unexpected error occurred. request_id: req_demo_001 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Brightalk API key description: Use a private-beta server credential in the Authorization header. ````