vicigeeksimple guides
Browse
Data and integrations

Automate tasks · Integration patterns

Reconcile an uncertain VICIdial API write before retrying

Run a local four-case decision fixture, then use its exact target/before/after contract to distinguish an applied write, a non-applied write, a conflict and an unknown outcome.

Start the guide
By Vicigeek Editorial DeskSafe practice lab2 minute readUpdated November 7, 2026

1. Name the exact write and independent observation

The teaching operation is update_lead for one synthetic lead, changing comments from model-A to model-B. This is a contract worksheet, not an executed API request. The native owner must review required permissions, installed search behavior, field limits and side effects before any future use.

Record the exact lead identity and observed before-value through a separate approved read/UI path. A phone number alone is not a unique lead identity. Decide how concurrent edits are detected; if the interface cannot condition the write on the reviewed state, keep the test isolated and do not automate a reversal.

Before you use it
This worksheet has no endpoint or credentials and sends nothing. Read the installed function contract before any native operation.
Fictional operation contract
function=update_leadsearch_method=LEAD_IDlead_id=YOUR_APPROVED_SYNTHETIC_IDcomments=model-Bbefore observed independently=model-Aexpected after=model-B
Not executed · worksheet or reference text

This sample is a template or reading aid, not a terminal command. There is no output to show.

Success looks like
A reviewer can name one identity, field, before-state, intended after-state and independent read path.
Stop if
Ambiguous identity, concurrent edits or unknown side effects block the native write.

You should seeThe request’s intended state transition is explicit before interpreting an acknowledgement.

Prepare the protected read-only API exercise first

2. Reproduce the four lost-acknowledgement decisions locally

Assume the response was lost. The writer must not retry immediately. An independent observation of the exact target/field is compared with the preserved before and desired states.

The local model below sends no request and writes no record. It makes the four decisions reproducible. A native observation must come from the actual authorized read path, not the writer’s cache or the same mistaken phone search.

Before you use it
Run locally with Python 3. model-A/B/C are invented field values; no real account or target is used.
Run the complete four-case reconciliation fixture
python3 - <<'PYDECIDE'def decide(observed,before='model-A',desired='model-B'):    if observed is None: return 'UNKNOWN: owner investigation; no automatic retry'    if observed==desired: return 'APPLIED: record success; do not replay'    if observed==before: return 'NOT APPLIED: review cause before one approved retry'    return 'CONFLICT: preserve concurrent state; no automatic retry or reversal'cases=[('desired observed','model-B','APPLIED'),('before observed','model-A','NOT APPLIED'),       ('third value observed','model-C','CONFLICT'),('read unavailable',None,'UNKNOWN')]for label,value,prefix in cases:    result=decide(value); assert result.startswith(prefix),(label,result)    print('PASS',label,'->',result)print('Fictional reconciliation model only; no API request or record changed.')PYDECIDE
Reader-run example · not executed for this guide

This example has no recorded result here. Follow its preparation, expected result and stop conditions before using it.

Success looks like
All four assertions pass: APPLIED avoids replay, NOT APPLIED requires reviewed retry, CONFLICT preserves concurrent state and UNKNOWN blocks guessing.
Stop if
A failed assertion leaves the model unaccepted. A native read that cannot verify exact identity/value remains UNKNOWN.

You should seeThe lost response is separated from whether the intended mutation actually happened.

3. Apply the decision record before any later native retry

  1. For an independently observed desired state, record the operation as applied and do not replay it.
  2. For the exact preserved before-state, investigate transport/permission/parameter cause and the function’s duplicate behavior before the owner approves a retry. A delayed writer still needs to be ruled out.
  3. For any third value, protect the concurrent edit and hand off a conflict. For an unavailable or ambiguous read, record UNKNOWN and block dependent work.
  4. Record function/build, opaque target reference, before/desired state, request time, independent observation time, response class and decision. Any rollback is another separately reviewed write and must check current state first.

You should seeThe exercise ends with a reproducible decision and explicit native prerequisites; it does not claim a completed VICIdial write.

Run the durable local receipt/replay/conflict lab

Checks and sources

What was checked

  • The four-case decision example is a local fictional model with no API request or mutation.
  • The native update_lead worksheet is unexecuted and depends on the installed contract, function permissions and independent exact-target observation.
  • No arbitrary automatic retry, write idempotence, concurrent-edit protection or production result is claimed.
  • No native API write or before-and-after response was captured for this guide. The executable local fixture models four decisions using fictional state and does not contact VICIdial.

Primary references

Sources

  1. VICIdial Non-Agent API referenceVICIdial Group · accessed November 4, 2026
  2. VICIdial Agent API referenceVICIdial Group · accessed November 4, 2026